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 both security secrets.
  • ./data is writable and has free disk space.
  • WORKERS=1 is set.
  • Port 5054 is not already in use.
  • The data directory is not being mounted by another MyBibliotheca process.

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 locked or KuzuDB errors

  • Stop duplicate application instances.
  • Confirm there is only one worker.
  • Check disk space and permissions.
  • Review the most recent startup logs.
  • Make a copy of the data directory before recovery work.

Do not remove lock or database files as a first response. If corruption is suspected, stop the application and work from a backup or a copy.

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 Kuzu 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