Troubleshooting
Operational problems and how to diagnose them. For storage-specific issues see Storage Troubleshooting; for update/rollback issues see Updates → Troubleshooting.
Each entry follows Symptom → Cause → Diagnose → Fix → Verify.
Startup & Containers
Backend exits immediately with a database error
- Symptom:
ytmdl-backendrestarts in a loop; logs mentionMUSICDL_DATABASE_URLorMUSICDL_DATABASE is no longer supported. - Cause: Missing/incorrect
MUSICDL_DATABASE_URL, or a removed SQLite variable (MUSICDL_DATABASE,YTDM_DATABASE_PATH) is still set. - Diagnose:
podman compose -f compose.ghcr.yaml logs backend | head. Check that the password inMUSICDL_DATABASE_URLmatchesPOSTGRES_PASSWORD. - Fix: Set a valid
postgres://ytmdl:<pw>@db:5432/ytmdl?sslmode=disableand remove any SQLite variables from.env. - Verify:
curl -fsS 'http://127.0.0.1:8080/api/v1/health?scope=essential'returns HTTP 200.
Frontend returns 502 Bad Gateway after recreating the backend
- Symptom: UI unreachable through the frontend after
up -d --force-recreate backend. - Cause: Historically, an nginx literal upstream cached the old backend IP.
- Status: Fixed. The frontend resolves
backendper request via a templatedresolver. If you still see this, you are on an old frontend image — update, orpodman compose -f compose.ghcr.yaml restart frontend. - Verify:
podman exec ytmdl-frontend nslookup backendresolves, and the UI loads.
preflight engine compatibility check failed: detected python 'podman-compose'
- Cause: Podman is delegating
podman composeto the legacy Pythonpodman-compose(1.3.x or older), which lacks Compose v2 features YTMDL needs. - Fix: Install a Compose v2 provider (Docker Compose plugin). Confirm with
podman compose versionreporting Docker Compose v2. - Verify:
ytmdlctl statuscompletes without the preflight error.
ambiguous compose files found / ambiguous engine selection
- Cause: More than one
compose.*.yamlis present andytmdlctlwill not guess for a mutating command. - Fix:
ytmdlctl status --file compose.ghcr.yaml --engine podman --save. - Verify: Subsequent
ytmdlctlcommands no longer prompt for a file.
Downloads & Jobs
A job sits at "Wartet auf Provider"
- Symptom: Job/item badge reads Wartet auf Provider; nothing seems to progress.
- Cause: The media provider or an authenticated session is in a temporary cooldown (
SESSION_UNAVAILABLE) — a rate limit or a verification challenge. - Diagnose: Settings → Media Sources shows the session state and
cooldown_until.bot_challengecooldowns are 24 h (first) or 72 h (repeated). - Fix: Usually none — it resumes automatically. If the state is Anmeldung erforderlich (
auth_failed), upload a freshcookies.txt. Add another managed session to spread load. - Verify: After the cooldown, the item moves to
downloadingon its own; a successful download clears the session's protection immediately.
Downloads never start, everything stays "In Warteschlange"
- Cause: The queue is globally paused (storage maintenance, or the Storage Guard tripped), or
MUSICDL_CONCURRENT_DOWNLOADSworkers are all blocked. - Diagnose: Settings → Storage — is Download-Warteschlange showing Pausiert? Check
GET /api/v1/storage/status. - Fix: Resolve the storage condition, then Warteschlange fortsetzen.
- Verify: The paused banner clears and jobs advance.
Job shows "Abgeschlossen" but some tracks are missing
- Symptom: Job status is Abgeschlossen with a non-zero failure count.
- Cause: Individual track failures do not fail the whole job by design.
- Fix: Open the job → Fehlgeschlagene wiederholen, or retry a single item. Check each failed item's error (not found, match score too low, provider cooldown).
- Verify: Re-run leaves 0 failed items, or the remaining ones have a clear terminal reason (e.g. track genuinely unavailable).
Historical: jobs stuck forever in downloading, infinite retry loops
- Status: Fixed across v0.20.1–v0.26.0. Protected states (
BOT_CHALLENGE,RATE_LIMITED,SESSION_UNAVAILABLE) now hold items inretry_waitwithout consuming retry budget; genuinely unusable configurations fail terminally instead of looping; crash recovery resets in-flight items topending/queuedon start. If you see a permanentdownloadingitem, restart the backend once and report it.
Tab badge counts look wrong
- Status: Fixed in v0.25.1 (badges reflect global DB totals, not the visible page) and refined in v0.27 (open-job badge counts active + queued and hides at zero).
Subscriptions
A subscription created a duplicate job
- Status: Fixed in v0.25.2 — deduplication now also considers paused non-terminal jobs (
HasNonTerminalJob) and enqueue is serialised. Ensure both containers are current.
Subscription sync times out on a huge discography
- Cause: The catalogue walk exceeded
MUSICDL_SUBSCRIPTION_SYNC_TIMEOUT(default30m). - Fix: Raise the timeout, or reduce
MUSICDL_SUBSCRIPTION_BATCH_SIZEpressure. Admission is bounded to one concurrent walk on purpose. - Verify: The next scheduled sync completes and the subscription's last sync report is green.
Player
No sound, or "format not supported"
- Cause: The browser cannot decode that container/codec (commonly Ogg/Opus in Safari).
- Diagnose: Open the same track in Chromium or Firefox.
- Fix: Use a supported browser for that file. YTMDL does not transcode on the fly. See Player → Known Browser Limitations.
EQ / crossfade / visualizer do nothing on iPhone
- Cause: iOS Safari requires a user gesture to start audio and has Web Audio routing limitations.
- Fix: Tap play directly; expect reduced Web Audio behaviour on iOS. Basic playback still works.
Playback stops when I navigate
- Status: Fixed in v0.25 / refined in v0.27 — the player context and audio state persist across in-app navigation and browser Back/Forward. If it still drops, you are on an old frontend image.
Health & Diagnostics quick reference
sh
# Container-level (never contacts external services)
curl -fsS 'http://127.0.0.1:8080/api/v1/health?scope=essential'
# Full local diagnostics (adds yt-dlp / ffmpeg / ffprobe checks)
curl -fsS 'http://127.0.0.1:8080/api/v1/health'
# Storage (admin session required)
curl -fsS 'http://127.0.0.1:8080/api/v1/storage/status'
# Logs
podman compose -f compose.ghcr.yaml logs -f backendA missing tool makes /api/v1/health report degraded but still HTTP 200. Only an unreachable database returns HTTP 503.
