JellyPassTroubleshooting and FAQ
Start with the logs and the health check:
docker compose logs --tail=100 jellypass
curl http://127.0.0.1:8787/healthThe container stops with EACCES: permission denied
The container runs as UID 1000 and can't write the data folder. Run sudo chown 1000:1000 data and start it again.
The container stops with a settings error
JellyPass checks its settings at startup and names the one that is wrong, for example SEERR_URL and SEERR_API_KEY must be configured together, or a missing TMDB_API_KEY while HOUSEHOLD_APP_ENABLED is on. See the Settings reference.
A new title is in Library but not in Grants
A title becomes private only when Seerr's webhook arrives, the backfill finds its request, or an administrator assigns it. Common causes: it was downloaded outside Seerr, it replaced media Seerr already had, it arrived before the webhook was set up, the requester's Seerr account isn't linked to Jellyfin, or the webhook is off, filtered to the wrong event, unreachable or using the wrong token. Assign it from Library, and set up the backfill.
The webhook gets 401
The bearer header or ?token= doesn't exactly match WEBHOOK_TOKEN. Check for copied whitespace.
The webhook reports missing Jellyfin IDs
Set SEERR_URL and SEERR_API_KEY and use the request-ID-only payload, and make sure the requester was imported from Jellyfin.
A household address answers 404
Check that the household exists, that its ID is lowercase letters, numbers and hyphens, that HOUSEHOLD_DOMAIN and HOUSEHOLD_HOST_PREFIX match the address, and that the proxy passes the original Host.
The admin site says this is not a tested Jellyfin version
Jellyfin runs a version JellyPass doesn't support, or JellyPass can't read Jellyfin's version yet. In 3.x household addresses keep serving; JellyPass only warns until an administrator confirms that exact version. From 4.0.0, household addresses will answer 503 until then. See Jellyfin versions.
A household address shows the JellyPass admin sign-in
The name reaching JellyPass isn't a household address, so JellyPass treats it as the admin site. Check the prefix and domain settings, and that the proxy passes Host unchanged.
The Library tab is empty or out of date
Check that JellyPass can reach Jellyfin and that the API key is an administrator's, then run Sync library. CATALOG_SYNC_INTERVAL_SECONDS=0 turns off automatic syncs.
Changes don't reach every user
In Grants, preview a reconciliation, check the changes and apply them. New Jellyfin users are covered at the next reconciliation.
FAQ
- Does a sync make my whole library private?
- No. The catalogue is only an inventory. Titles become private through a request or an administrator.
- Can a member see what another household asked for?
- No. The apps never show who asked for a title or which household has it, and a title another household holds looks the same as one nobody has.
- Do I need the apps?
- No. Members can keep requesting in Seerr and watching in any Jellyfin app on their household address. The apps add Get this, My requests and discovery.
- Does it support request quotas?
- Not in the apps: a member with a Seerr request quota sees titles as "Can't request" and can still use Seerr.
- Can I use more than 100 households?
- Only with the household app off.
- Where do I report a bug?
- In GitHub issues. Report security problems privately (see Security).