Troubleshooting
FFmpeg Not Found
Symptom: The setup health check shows a warning for "FFmpeg". Downloads fail.
Solution: FFmpeg must be available on PATH. The official Docker image includes it. If you run FunkArr without Docker, install FFmpeg and verify that ffmpeg -version works in your shell.
FFmpeg Errors During Download
Symptom: Downloads start but fail during remux. The history shows an error message containing "ffmpeg".
Possible causes:
- The source URL has expired. Mediathek stream URLs are only valid for a limited time. Retry the download.
- The HLS stream is incomplete or has been removed by the broadcaster.
- Not enough disk space in the incomplete directory.
Debug: Set the log level to Debug to see full FFmpeg commands and output:
Serilog__MinimumLevel__Default=DebugMediathekViewWeb API Timeouts
Symptom: Search requests from Sonarr/Radarr return no results or take a very long time.
Solution:
- Check reachability: Open
https://mediathekviewweb.de/in a browser. - Check the health check: Go to the Setup page in the web UI or call
/api/system/setup. - The MediathekViewWeb API occasionally experiences load spikes. Wait a few minutes and try again.
Ruleset Sync Failed
Symptom: Community rulesets are not updating. The version on the dashboard does not change.
Solution:
- Check that
FunkArr__RuleSet__RefreshEnabledistrue(default). - Check that the configured repository (
FunkArr__RuleSet__Repository) is reachable. - Check that the container has internet access (the GitHub API must be reachable).
- If you pinned a specific version (
FunkArr__RuleSet__Version), no newer version will be downloaded. Set it back tolatest.
Sonarr/Radarr Returns No Results
Symptom: Searches in Sonarr or Radarr return no hits even though the content exists in the Mediathek.
Solution:
- Ruleset exists? Check in the web UI under "Rulesets" whether a ruleset exists for the show you are looking for. Without a ruleset, FunkArr cannot map the Mediathek title to the Sonarr/Radarr series.
- Correct IDs? The ruleset must contain the correct TVDB ID (series) or TMDB ID (movies) so Sonarr/Radarr can recognize the match.
- API key? Verify the API key in Sonarr/Radarr matches the FunkArr key.
- Indexer test? Run an indexer test in Sonarr/Radarr. If it fails, the URL or the key is wrong.
- Interactive search: Use interactive search in Sonarr/Radarr to see what results FunkArr returns.
Downloads Stuck
Symptom: Downloads stay at "Processing" permanently without progress.
Solution:
- Check whether the download pipeline is paused (top-right on the Activity page).
- Check whether there is enough disk space in the incomplete directory.
- Check the container's network connection.
- Restart the container. Incomplete downloads are cleaned up on restart.
- Increase
FunkArr__Download__ConcurrentDownloadsif the server is under heavy load and downloads are waiting in the queue.
Subtitle Conversion (TTML to SRT)
Symptom: Subtitles are missing from the finished MKV file even though the Mediathek offers subtitles.
Solution:
- FunkArr automatically converts TTML subtitles (the format used by many Mediatheken) to SRT and embeds them as a German-language track in the MKV file.
- If subtitles are missing, the source may not offer any. Not all Mediathek entries have subtitles.
- Enable debug logging to see whether subtitles are found and processed.
PostgreSQL Connection Issues
Symptom: FunkArr does not start or shows database errors when PostgreSQL is configured.
Solution:
- Check that all Postgres variables are set:
FunkArr__Postgres__Host,User,Password,Database. - Check that the PostgreSQL instance is reachable and the user has access.
- With Docker Compose: Use
depends_onwith a health check so FunkArr only starts when PostgreSQL is ready:
services:
funkarr:
depends_on:
db:
condition: service_healthy
db:
image: postgres:17-alpine
healthcheck:
test: ["CMD-SHELL", "pg_isready -U funkarr"]
interval: 5s
timeout: 3s
retries: 5A complete PostgreSQL Docker Compose configuration is available in docker-compose.postgres.yml in the repository.
- Without
FunkArr__Postgres__Host, FunkArr falls back to SQLite automatically.
Container Fails to Start
Symptom: The Docker container starts and exits immediately.
Solution:
- Check the container logs:
docker compose logs funkarr - Common causes:
- Missing or incorrect environment variables
- Volume mount path does not exist on the host
- Port conflict (another service is using the configured port)
- Not enough memory or CPU
Enable Debug Logging
For detailed troubleshooting, set the global log level to Debug:
Serilog__MinimumLevel__Default=DebugIndividual areas can be made more verbose separately:
| Variable | What it shows |
|---|---|
Serilog__MinimumLevel__Default=Debug | All areas |
Serilog__MinimumLevel__Override__Akka=Information | Actor system messages |
Serilog__MinimumLevel__Override__Microsoft.AspNetCore=Debug | HTTP request details |
Valid levels: Verbose, Debug, Information, Warning, Error, Fatal.
WARNING
Debug logging produces a lot of output. Use it only temporarily for troubleshooting and reset it to Information afterwards.
Health Check Endpoints
For automated monitoring, FunkArr provides three endpoints:
| Endpoint | Purpose |
|---|---|
/healthz | Full health check (data, complete and incomplete directories writable, FFmpeg on PATH, MediathekViewWeb reachable) - returns 503 if a directory or FFmpeg check fails; an unreachable MediathekViewWeb only reports Degraded (200) |
/alive | Simple liveness probe - always returns 200 |
/api/system/setup | Detailed setup validation with individual check results |
Use /healthz for Docker health probes:
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:6969/healthz"]
interval: 30s
timeout: 5s
retries: 3