Troubleshooting

Each entry is symptom → likely cause → fix.

Recorder won’t start

”Server mode config invalid”

The recorder refuses to start when env-managed server mode settings are mixed or incomplete. Dashboard-saved invalid settings degrade to setup-required mode so the UI remains reachable.

Cause — SERVER_MODE is direct without a public HTTPS WEBHOOK_CALLBACK_URL, relay without matching RELAY_INGEST_URL / RELAY_SUBSCRIBE_URL, or relay URLs were set without a server mode.
Fix — leave SERVER_MODE empty and configure server mode in the dashboard, set SERVER_MODE=poll, configure direct EventSub correctly, or set up the Connect relay.

”database is locked”

SQLite-only. Two processes are trying to write to the same file.

Cause — leftover container from a previous run, or a backup tool holding a write lock.
Fix — docker compose down, confirm no stray replayvod process is running, then start again.

”can’t find ffmpeg”

Native (non-Docker) install only. The Docker image bundles ffmpeg.

Cause — ffmpeg isn’t on PATH.
Fix — install ffmpeg system-wide, or set PATH for the recorder’s user.

Cause — the OAuth redirect URL on the Twitch app doesn’t match what the recorder advertises.
Fix — open dev.twitch.tv/console/apps, edit your app, set the OAuth redirect to exactly ${PUBLIC_BASE_URL}/api/v1/auth/twitch/callback.

”user not allowed”

Cause — WHITELIST_ENABLED=true and the Twitch user isn’t in WHITELISTED_USER_IDS or OWNER_TWITCH_ID.
Fix — add the user’s numeric Twitch ID to WHITELISTED_USER_IDS (comma-separated) and restart.

Streams aren’t being recorded

Walk this list in order:

Is the channel followed by your owner account? ReplayVOD only watches channels followed by users known to it.
Does any schedule match? Open Schedules in the dashboard. A rule with no filters matches everything; if you have only restrictive rules, nothing matches the live stream.
Is live detection working? Open System → EventSub. Server mode should be poll, direct, or relay and active. If setup required or restart required is shown, finish setup or restart the server so the recorder can receive live events.
Is the recorder under-provisioned? Check [download].max_concurrent — running recordings are visible in the Live tab.

EventSub not delivering

Subscriptions stuck in `webhook_callback_verification_pending`

Cause — Twitch couldn’t verify your callback within a few seconds. Most often a wrong URL, an unreachable host, or HTTP instead of HTTPS.
Fix — confirm curl https://your-domain.example/api/v1/webhook/callback returns 200 from a public host (not just from inside your network). Then restart the recorder; reconcile re-creates the subscriptions.

Subscriptions stuck in `webhook_callback_verification_failed`

Cause — verification reached your endpoint but the challenge string in the response body wasn’t echoed back verbatim.
Fix — the recorder handles verification automatically. If you’ve put a reverse proxy in front of it, ensure the proxy forwards the raw body without modification or rewriting.

Recordings come out broken

”incomplete” badge on a recording

Cause — segment loss exceeded [download].max_gap_ratio. The video plays; the badge is a heads-up.
Fix — investigate network or CDN issues during the broadcast. If routine, raise max_gap_ratio (default 0.01).

Recording stops mid-stream

Cause — the recorder considered the stream offline. Common when the broadcaster’s connection drops.
Fix — [download].max_restart_gap_seconds controls how long the recorder waits before splitting into two VODs. Raise it if you’d rather get one file with a gap.

Logs

Enable file logging in server/config.toml:

[logging]
log_to_file = true
log_dir     = "./logs"
log_level   = "info"

debug is verbose enough to track down most issues.