Troubleshooting

Troubleshooting

"Cover-file is not a valid image file, or could not be stored"

Fixed in v4.0.13 and later. If you're still seeing it after upgrading, you probably have root:root-owned book directories from a pre-fix install. Run once:

docker exec calibre-web chown -R abc:abc /calibre-library

"Generate Kobo Auth Token" returns a blank page

Fixed in v4.0.14 and later. Upgrade the image.

Kobo says "Sync failed, please try again"

Almost always one of these:

1. The device isn't reaching your server. The api_endpoint= line in .kobo/Kobo/Kobo eReader.conf must point at your CWA address (not storeapi.kobo.com), and that address must be reachable over HTTPS. See Kobo Sync.
2. A Kobo account is signed in and Proxy unknown requests to Kobo Store is off, so the device's store calls get an empty response mid-sync. Turn that setting on, or sign out of the Kobo account on the device.
3. Behind a reverse proxy, the proxy can't reach the container. Confirm the proxy target is http://<host>:8083 and that the certificate is valid.
4. nginx is silently dropping the sync response because its default buffers are too small for Kobo's library-sync headers. The CWA log shows the request arriving but nothing else; the nginx error log shows upstream sent too big header. Add proxy_buffer_size 32k; proxy_buffers 4 32k; proxy_busy_buffers_size 64k; to the proxy location. See the nginx buffer sizes note.

"Database is locked" / app frozen

If your library is on a network share, set NETWORK_SHARE_MODE=true (see Configuration). On local disk, this usually means a previous container shutdown was unclean: restart Docker, then the container.

Session Protection warnings, forced re-login on every page

Set TRUSTED_PROXY_COUNT to match your proxy depth. See Reverse proxy.

Books in /cwa-book-ingest aren't picked up

Three common causes:

1. Files owned by root. Make sure ingest files are owned by your PUID:PGID user.
2. Watcher missed them. Click the Refresh Library button on the navbar; it does a one-shot scan.
3. Format isn't allowed. Check Admin → CWA Settings → Ingest for your allowed formats.

Default login isn't working

The defaults are admin / admin123 (lowercase). If you've already changed the password and forgotten it: stop the container, delete config/app.db, and restart. This resets the database. User accounts are lost; the library itself is untouched.

Something else

Check the issue tracker or open a new issue. Useful information:

• The version: docker exec calibre-web cat /app/CWA_STABLE_RELEASE
• Recent logs: docker logs calibre-web 2>&1 | tail -50
• What you did and what you expected to happen

You can also ask on Discord for faster back-and-forth.