Common problems, their likely causes, and fixes. If nothing here matches, collect a diagnostic bundle and reach out through the support page.
| Symptom | Likely cause | Fix |
|---|
| Container exits immediately | DATABASE_URL missing or wrong | Check docker compose logs odeion. Set DATABASE_URL to local for the embedded database or a valid PostgreSQL DSN. |
port is already allocated | Another service owns the host port | Change the host port mapping in docker-compose.yml (the installation wizard has a Host port field). |
| Permission errors on volumes | PUID/PGID mismatch | Set them to the owner of your media and data directories; run id on the host to find your IDs. |
First start is slow with local database | Embedded PostgreSQL downloads on first run | Expected once. Binaries land in the data directory and are reused afterwards. |
| External database connection refused | Network, credentials, or SSL mode | Test with psql using the same DSN. Special characters in the password must be percent-encoded in the URL. |
| Symptom | Likely cause | Fix |
|---|
| Web works, apps refuse to connect | Apps require HTTPS | Put a reverse proxy with a valid certificate in front of the server. |
| Device link codes fail | Base URL wrong or not publicly reachable over HTTPS | Set the base URL in Admin > Settings > General to your public HTTPS address. See Device Linking. |
| Watch Together or live updates broken behind nginx | WebSocket headers stripped | Use the nginx config from the reverse proxy guide; it forwards Upgrade/Connection and disables buffering. |
| Backup upload fails through proxy | Proxy body size limit | client_max_body_size 0 (nginx) or the equivalent for your proxy. |
| Symptom | Likely cause | Fix |
|---|
too many attempts on login | Rate limiting after 10 failures per 15 minutes | Wait out the window; a successful login clears the per-user counter. |
account is locked | An admin locked the account | Unlock in Admin > Users, or use the CLI escape hatch below. |
| Only admin locked out, nobody can fix it | No second admin | Run odeion reset-password <username> on the server host. It prints a reset link and clears the lock. See Password Reset. |
| All logins refused | Login kill switch is on | Turn it off in Admin > Settings > Operations. |
| OAuth button missing or failing | Provider disabled, or redirect URI mismatch | Check Admin > Settings > Authentication and the provider console redirect URI. See OAuth and SSO Providers. |
| Invite code rejected | Expired, used up, or registration kill switch | Check the invite’s expiry and use count in Admin > Users; check the Registration kill switch. |
| Symptom | Likely cause | Fix |
|---|
| GPU not used for transcoding | Device not passed through, or pool disabled | Verify /dev/dri (VAAPI) or the NVIDIA toolkit is configured, then check pool status in Admin > Transcoding > Pools. See Transcoding. |
| Stuttering and rebuffering under load | Slow transcode cache storage | Move the cache directory to fast local storage; see Storage. |
| GPU pool silently skipped | GPU health check failed | Odeion bypasses unavailable GPUs and falls back to lower-priority pools; check driver state and re-probe the pool. |
| Playback refused for everyone | Playback kill switch | Check Admin > Settings > Operations. |
| Subtitles missing from picker | Extraction disabled or unsupported format | Text formats extract automatically when enabled; bitmap formats need burn-in during transcoding. See Subtitles. |
| Symptom | Likely cause | Fix |
|---|
| New files not appearing | Scan has not run, or path not mounted | Trigger a scan from the admin panel; confirm the library path is mounted into the container. |
| Scans never start | Scanning or background-tasks kill switch | Check Admin > Settings > Operations. |
| Tasks stuck or failing | Inspect the task error | Admin > Tasks shows per-task status and errors, with retry buttons. |
| Wrong metadata match | Matching picked the wrong title | Fix the match from the item’s admin page; .nfo or .plexmatch sidecars force correct IDs. See Libraries. |
- Check the logs:
docker compose logs -f odeion, or Admin > Logs in the web UI. Raise file_log_level to debug for more detail; see Debugging.
- Collect a diagnostic bundle with
odeion doctor. It is redacted by default and safe to share.
- Reach out through the support page with the bundle attached.
