Skip to content

Troubleshooting

Start with the symptom, then check the application logs. Keep the exact error message, version, deployment method, and the steps that led to it when asking for help.

The container will not start

docker compose ps
docker compose logs --tail=200 bibliotheca

Check that:

  • .env exists and contains unique SECRET_KEY, SECURITY_PASSWORD_SALT, and POSTGRES_PASSWORD values.
  • PostgreSQL is healthy: docker compose ps and docker compose logs postgres.
  • ./data is writable and has free disk space.
  • Port 5054 is not already in use.
  • The data directory is not mounted by another MyBibliotheca process.

If Compose says one of the required settings is missing, run python3 scripts/setup_docker.py from the MyBibliotheca checkout, then start Compose again. The script fills missing values and preserves existing non-empty settings. If PostgreSQL already has data, keep the password that was originally used to initialize it.

PostgreSQL reports password authentication failed

If the app logs show password authentication failed for user "bibliotheca", the POSTGRES_PASSWORD in .env may not match the password stored in the PostgreSQL data volume. PostgreSQL reads the Compose password only when it initializes a new volume; changing .env later does not change the database role password. This can happen if .env was regenerated while an older postgres_data volume remained.

If the database contains data you need, do not delete the volume. Restore the original POSTGRES_PASSWORD in .env, or reset the database role password to the current value in .env:

docker compose exec -u postgres -it postgres psql -d postgres

At the psql prompt, enter the password-change command for role bibliotheca and follow the prompts, using the current POSTGRES_PASSWORD from .env as the new password. Then exit psql and restart the app:

docker compose restart bibliotheca
docker compose logs -f bibliotheca

The site loads but the library is empty

Check the mounted data path and confirm that the container is using the same ./data directory as before:

docker inspect mybibliotheca --format '{{json .Mounts}}'
ls -la data

Do not initialize a new database or delete files until you have identified the original data directory.

Database or migration errors

  • Check docker compose ps and the logs for both bibliotheca and postgres.
  • Confirm .env database settings match the Compose PostgreSQL service.
  • If migrating from Kuzu, follow the blocker shown by Admin ā†’ Database Migration. The wizard keeps Kuzu active until verification succeeds.
  • Do not remove lock or database files or edit persistence state by hand. Make a copy of the data directory before recovery work.

For the full migration sequence, see Kuzu to PostgreSQL migration.

Import problems

Symptom What to check
File rejected Use UTF-8 and an accepted .csv, .tsv, or .txt extension in the advanced importer
Columns look wrong Confirm the delimiter and header row; inspect the preview
ISBNs become numbers Re-export or format the spreadsheet ISBN column as text
Books are missing Check skipped/error counts and download the error report
Covers or titles are missing Review provider availability, then run repairs
Duplicates appear Check ISBN/title/author matching and the merged count
Reading history is unmatched Use the book-matching step before finalizing the import

See Importing books for the complete workflow.

Repair problems

If ISBN or cover repairs skip many records:

  1. Open a sample title and check the spelling of the title and contributor.
  2. Check whether the book already has an identifier or cover URL.
  3. Retry later if the provider was rate-limited.
  4. Resolve the remaining records manually.

Repairs intentionally leave weak or ambiguous matches unchanged.

Login and CSRF errors

Refresh the page, confirm cookies are enabled, and verify that the site is accessed through one consistent hostname. If the problem persists, inspect the application logs and confirm the reverse proxy is not stripping headers or changing the scheme.

Privacy or public-library results look wrong

  • Open Settings ā†’ Privacy and confirm the intended sharing switches remain enabled after saving.
  • Share library contents controls whether books appear in the public library at all.
  • Current-reading results require Share what Iā€™m currently reading and reading-activity sharing.
  • Reading logs and completed-book activity require Share my reading activity and statistics.
  • A private or inactive user should contribute no books to the public-library view.

If a switch appears to save but reverts after reload, collect the application version and relevant container logs and report it as a bug. Do not edit the database directly.

Get help

Include:

  • MyBibliotheca version
  • Docker or source deployment
  • Operating system and browser
  • Exact steps to reproduce
  • Relevant logs with secrets and personal data removed