Whisparr Not Working? Common Errors and Their Fixes

Almost every “Whisparr is broken” report falls into one of five buckets: the UI will not load, indexers fail, the queue is stuck, downloads never import, or the logs are full of permission errors. Work through this page top to bottom — each section starts with the fastest check and ends with the deeper fix.

1. The web interface will not load

Fast check: is the process or container actually running? For Docker, docker ps should list it; if it restarts in a loop, read docker logs whisparr — the last lines almost always name the cause.

Common causes:

• Port conflict: another service already owns 6969. Change the host-side port mapping and try again.
• Wrong address: from another device, use the server's LAN IP, not localhost.
• Corrupt config after a crash: restore your config folder from backup — this is why we nag about backing it up in every guide.

2. Indexer errors

Open Settings → Indexers and press Test on each one. Failures usually mean an expired or wrong API key, a changed indexer URL, or rate limiting after too many rapid searches. If Prowlarr manages your indexers, fix the entry in Prowlarr and let it re-sync rather than editing Whisparr directly. Persistent timeouts from inside a container can also indicate a DNS problem in Docker — restarting the container or setting an explicit DNS server usually resolves it.

3. Grabs sit in the queue forever

Check the Activity queue's status column. If items show as queued but the download client shows nothing, re-test the download client connection in Settings — a changed password or port silently breaks the hand-off. If the client is downloading but Whisparr shows no progress, the client's category for Whisparr is likely missing or renamed.

4. Downloads complete but never import

This is the classic path-mismatch problem. Whisparr must be able to reach the completed files at the same path meaning it expects:

• Same-machine Docker setups: both containers should share one /data mapping. If the client saves to /downloads while Whisparr looks in /data/downloads, imports fail even though the files exist.
• Split setups (client on another machine): add a Remote Path Mapping in Settings → Download Clients that translates the client's reported path to the path Whisparr sees.
• Slow imports that eventually finish are not broken, but they mean copies instead of hardlinks — restructure toward a single data parent as shown in our Docker guide.

5. Permission denied on /config or media folders

In Docker and on NAS platforms, the container runs as the PUID/PGID you provided. Those IDs must own the config folder and have write access to the media folders. Verify with ls -ln on the host and correct either the folder ownership or the environment values. On Synology and TrueNAS, redo the shared-folder / ACL permissions for the exact user those IDs belong to.

Still stuck? Read the logs properly

System → Logs inside the UI (or the container logs) tells you more than any forum thread. Set the log level to Debug temporarily, reproduce the problem once, and read the first error line — not the last. The first error is the cause; the rest are consequences.

Download Now