Troubleshooting

“Narratorr isn’t connected yet” on search

Search and requests need the narratorr connection. An admin must set the narratorr host, port, and API key on the Settings page and Test it. Until then, search returns this notice.

Container crash-loops with SQLITE_CANTOPEN

The log shows ConnectionFailed("Unable to open ... database file") / SQLite error 14, repeating. The container runs as the non-root node user (uid 1000) and can’t write its data directory.

This happens with a host bind mount whose directory is owned by root. Fix the owner on the host and restart:

sudo chown -R 1000:1000 /path/on/host/narratorr-requests
docker restart narratorr-requests

A named volume avoids this entirely — see Installation.

App refuses to start in production

In production the app fails fast (rather than come up insecure) if:

• SESSION_SECRET is unset — set it (openssl rand -hex 32).
• AUTH_BYPASS is enabled — it’s refused entirely in production; set AUTH_BYPASS=0.
• No auth method is enabled — enable LOCAL_AUTH and/or configure an OIDC provider.

Blank page (or can’t log in) over plain HTTP

The app renders a blank page, or the page loads but sign-in silently fails, on a production deploy with no TLS in front (no reverse proxy terminating HTTPS). This happens because BEHIND_TLS defaults to NODE_ENV=production’s value — so a plain-HTTP prod deploy inherits the CSP upgrade-insecure-requests directive (the browser tries to upgrade asset requests to HTTPS, which don’t exist, and blocks them) and a Secure session cookie (which a plain-HTTP browser won’t send back).

Fix: set BEHIND_TLS=false if you’re genuinely running production over plain HTTP with nothing terminating TLS in front. Leave it unset (or true) once a reverse proxy / load balancer does terminate TLS — see Installation.

AUTH_BYPASS won’t bind a non-loopback host

By design — an AUTH_BYPASS instance has no auth, so it refuses to listen on anything but loopback. If you really mean to (an isolated host), set ALLOW_INSECURE_AUTH_BYPASS=1. Better: turn AUTH_BYPASS off and configure a real auth method.

A new user is stuck on “Awaiting approval”

That’s the approval queue working as intended. An admin approves them on the Users page (→ active). The very first user becomes admin automatically; if no one is admin yet, see BOOTSTRAP_ADMIN in Authentication.

OIDC sign-in fails (“Sign-in failed. Please try again.”)

The provider callback didn’t complete. Check that:

• The provider’s redirect URI exactly matches https://<your-public-url>/api/auth/oidc/<id>/callback.
• OIDC_<ID>_ISSUER, OIDC_<ID>_CLIENT_ID, and the client secret (if the provider requires one) are correct.
• Your reverse proxy forwards the callback to the app and TRUSTED_PROXIES is set so the right origin is used.

A request is stuck on “Processing”

Processing (acquiring) means narratorr is still working — searching, downloading, or importing. The timing is narratorr’s, not narratorr-requests’s: a request stays in Processing for as long as narratorr hasn’t imported the book yet (it may legitimately sit “wanted” until narratorr’s next scheduled search). Check the book’s state in narratorr. If it ultimately fails, the request flips to Failed with a reason.

Notifications aren’t arriving

• Confirm the notifier exists and its Test passes on the Settings page.
• Set the Public URL if you want the deep-link back to the queue in notifications.
• Remember notifications are admin-facing — they fire on a new request, a new-user signup, and a failed request. There is no requester-facing “your book is available” notification; requesters track status on their My Requests page (which updates live).

Checking health

GET /api/health reports readiness — it pings the database and reports whether narratorr is configured. The Docker image ships a matching HEALTHCHECK, so docker ps / your orchestrator will show the container as healthy/unhealthy.