Troubleshooting

Troubleshooting

"insecure production config" on start

You set TVTIMES_ENCRYPTION_KEY / TVTIMES_JWT_PRIVATE_KEY_PEM to a placeholder. Unset them and let the container generate real ones into /data, or supply genuine values.

Passkey registration fails

TVTIMES_PUBLIC_ORIGIN doesn't match the address bar exactly (scheme / host / port), or TVTIMES_WEBAUTHN_RP_ID isn't the origin's registrable domain, or you're on plain http:// and not localhost. See Reverse Proxy and HTTPS.

Sessions bounce to login on reload

Usually a proxy stripping cookies or a mismatched origin. The CSRF cookie must be visible at path / for the silent refresh to run.

Worker idle / guide not filling

docker compose logs worker

Check Redis is healthy and that the source's EPG panel shows a URL and an ok status. Hit Refresh on the source to force a full rebuild.

Source has channels but no programmes

The playlist didn't advertise an XMLTV feed. Attach one manually — see Sources → A source with channels but no guide.

HDHomeRun source: "not a private LAN address"

The address must resolve to an RFC1918 range (10., 172.16–31., 192.168.). Native HDHomeRun ingest deliberately requires a LAN address.

M3U / Xtream / XMLTV URL rejected: "resolves to a non-public address"

The SSRF guard blocks LAN targets by default. If it's a service on your own network, allow it:

TVTIMES_FETCH_ALLOWLIST=192.168.0.218      # or a CIDR: 192.168.0.0/24

then docker compose up -d --force-recreate.

Reminder emails don't arrive

console only logs them. Set TVTIMES_EMAIL_PROVIDER=smtp or resend (Email), and verify your account's email address — unverified accounts are skipped.

Upgrade "did nothing"

docker compose up -d can report Running without swapping the image. Use docker compose up -d --force-recreate after docker compose pull.