FAQ & troubleshooting
Does this work with Calibre-Web Automated?
Yes. CWA keeps Calibre-Web's OPDS feed unchanged; everything here works the same way against it.
Why do some books have id: null?
The OPDS entry itself carries only a UUID — the numeric Calibre id exists nowhere in it except inside the cover and download link hrefs. A book with no cover, requested by a user without the Download role, has neither link, so there is nothing to extract. The UUID is still returned; only get_cover is unavailable for that book (grant the Download role to fix it).
HTTP 401 on every call
Wrong CALIBRE_WEB_USERNAME / CALIBRE_WEB_PASSWORD. The OPDS feed uses the normal web login of the account — Calibre-Web has no separate API password. A 401 on a download URL specifically means the user lacks the Download role.
HTTP 403 on view: "read" / "unread"
Those feeds require a non-anonymous user with Show Read and Unread enabled in the user's view settings.
HTTP 404 on a view that should exist
Calibre-Web hides feeds according to the user's sidebar visibility settings (Admin → Edit User → View). A 404 on hot, rated or discover usually means that section is switched off for the configured user — or CALIBRE_WEB_URL does not point at the instance root.
"returned an HTML page instead of an Atom feed"
The URL points somewhere that answers with HTML — typically the instance root is wrong, or a reverse proxy in front of Calibre-Web served its own login page. The server refuses to parse HTML rather than producing a confusing XML error.
Why can't I change the page size?
It is a server-side setting (Admin → UI Configuration → Books per page, default 60). The OPDS feed paginates by it and offers no per-request override. Follow pagination.nextOffset instead of assuming a size.
A broad search fails with "larger than 8388608 bytes"
Calibre-Web returns every search match in a single response; on a huge library a one-letter query can exceed the 8 MB feed cap. Narrow the query — the cap is what keeps a hostile or misconfigured instance from exhausting memory.
Why is the cover so big / refused over 1 MB?
Calibre-Web serves the full-size cover on the OPDS cover route (the thumbnail aliases exist for client compatibility but serve the same file). get_cover refuses anything over 1 MB to protect the context window — for a larger scan, open the book's coverUrl in a browser instead.
Can it add books, edit metadata, or manage shelves?
No, and it will not. The OPDS feed is read-only; writing would mean driving Calibre-Web's session-based HTML forms, which is a different (and much more fragile) project. Every tool is a GET.
Where are the author / series / tag browsing tools?
search_books matches against title, authors, series, publisher and tags, which covers those lookups in practice. The index feeds exist in Calibre-Web, so dedicated tools are easy to add — open an issue with the use case.