Tome
Reference

Troubleshooting

Common problems and how to fix them. If yours isn't here, search existing issues or open a new one.

Reading time —

Books aren't appearing after upload

Three likely causes:

  • The scan is still running. Watch the progress bar at the top of the dashboard — a fresh scan of a few thousand files can take a minute.
  • The file format isn't supported. Tome handles EPUB, CBZ, CBR, and PDF. Anything else gets ignored silently.
  • Filesystem permissions. The container runs as UID 1000. If your /books mount is owned by root with mode 700, Tome can't read it. Fix the host-side ownership.

Covers are missing

The metadata fetch couldn't find anything, or the file had no embedded cover. Open the book detail page, click the cover, and use the Cover picker — it searches Google Books and Open Library, or you can upload a cover from disk.

KOReader "test connection" fails

Almost always one of:

  • The server URL baked into the plugin no longer matches your actual Tome URL (you moved to HTTPS, changed domains, etc.).
  • The API key was revoked from Tome's Settings page.

Fix: re-download the plugin from Settings → KOReader. The new .koplugin gets your current URL and a fresh key baked in. Replace the file in KOReader's plugins/ folder and restart.

Position not syncing between KOReader and web reader

Whichever side wrote most recently wins. If KOReader was offline for a while and then synced after you'd already advanced past that point in the web reader, the older KOReader position is rejected. Open the book again and the position will be correct.

If sync is silently broken, check Settings → KOReader → Recent sessions. Empty or stale entries mean the plugin isn't reaching the server.

Series view shows wrong volumes

Tome groups by the series + series_index on each book. If filename parsing got those wrong, the grouping will be wrong. Two fixes:

  • Edit metadata on the misgrouped book (book detail → Edit → Series fields).
  • Bulk-fix via Scribe: /scribe update "Series Name".

"Book not found" or 404 in the reader

The underlying file moved or was deleted from disk. Either restore the file to its previous path, or re-scan the library (Settings → Library → Re-scan) so Tome picks up the new layout.

Forgot admin password

Shell into the container and run the reset CLI: 

docker exec -it tome python -m backend.cli reset-password <username>

You'll be prompted for a new password. Existing JWTs survive (only the hash changed), so other devices stay signed in.

Reverse proxy 502 / 504

Usually one of:

  • Uvicorn took longer than the proxy's proxy_read_timeout. Bump it to 300s for endpoints that hit Hardcover / OpenLibrary or that scan large libraries.
  • Tome is not actually running. docker ps + docker logs tome.
  • Wrong upstream port — Tome serves on 8080 inside the container regardless of how you mapped it host-side.

Stats page is slow

Stats query the reading_sessions table, which grows linearly with use. SQLite handles up to ~hundreds of thousands of rows fine; beyond that, expect a second or two of aggregation. There's no flag to make it faster yet — but the indices are in place, so it's a constant factor, not a runaway query.

Permission errors on /books

The container runs as UID 1000 (user tome). If the host-side owner of your library folder is different, you'll see PermissionError in the logs and books won't import. Either chown -R 1000:1000 /path/to/books on the host, or pass user: "<your-uid>:<your-gid>" in your compose file to override.