FAQ & Troubleshooting

Answers to common questions and solutions to frequent issues.

General

What is Huntarr?

Huntarr is an automated media automation platform that works alongside your existing Sonarr, Radarr, Lidarr, Readarr, and Whisparr instances to hunt for missing content and quality upgrades — automatically and on a schedule you control. It also includes its own built-in modules: Movie Hunt (movie management), TV Hunt (TV management), Index Master (indexer manager), NZB Hunt (Usenet downloader), and Requestarr (media request system with multi-user support).

How does Huntarr differ from the built-in search in Sonarr/Radarr?

The *arr apps search when you manually trigger it or when new items are added. They don't continuously re-search for things that haven't been found yet, and they won't automatically look for quality upgrades on existing files. Huntarr fills that gap — it runs on your schedule, systematically works through your entire library, and keeps trying until everything is found or upgraded.

Does Huntarr replace Sonarr/Radarr?

Not necessarily — Huntarr works alongside them just as well as it can replace them. The third-party hunt engine uses their APIs to trigger searches. For users who want a fully self-contained setup, Movie Hunt and TV Hunt are built-in alternatives. But if you already have a working Sonarr/Radarr stack, Huntarr enhances it without requiring migration.

What ports does Huntarr use?

Huntarr's web UI runs on port 9705 by default. Change the host-side mapping in Docker (e.g., -p 9720:9705) or set the HUNTARR_PORT environment variable for source installs.

Is Huntarr free?

Yes. Huntarr is fully open source under the GPL-3.0 license. All features are free. If it's been valuable to you, a toward the developer's daughter's college fund is always appreciated but never required.

How do I get the latest version?

Pull the latest Docker image: docker pull huntarr/huntarr:latest then restart your container. On Unraid, click Update on the container in the Docker tab. See the Updating section for full details.

Installation

Docker container won't start

• Check that port 9705 isn't already in use on the host
• Verify your volume mount paths exist on the host and are writable
• Check container logs: docker logs huntarr
• Ensure the image pulled cleanly: docker pull huntarr/huntarr:latest
• Check for invalid timezone string in the TZ environment variable

"Permission denied" errors on /config or /downloads

• Set PUID and PGID to match the user who owns those directories
• On Linux: sudo chown -R 1000:1000 /path/to/config then set PUID=1000 PGID=1000
• On Unraid: set PUID=99 and PGID=100
• Ensure no other process has the directory locked

Huntarr is unreachable in the browser

• Verify the container is running: docker ps | grep huntarr
• Check that the host port mapping matches (e.g., 0.0.0.0:9705->9705 in docker ps output)
• Try accessing directly by IP: http://your-server-ip:9705
• Check firewall rules — ensure port 9705 (or your custom port) is allowed inbound
• On Unraid, verify the Docker network isn't set to "none"

App Connections

"API key invalid" error when adding an app

• Re-copy the API key from your *arr app: Settings → General → Security → API Key
• Ensure there are no leading/trailing spaces — paste into a plain text editor first to check
• Verify the URL is correct and includes the full port
• Test the URL directly in your browser — it should load the *arr web UI

Can't connect to a *arr app

• If both Huntarr and your *arr app are in Docker on the same network, use the container name as hostname: http://sonarr:8989
• If they're on different networks or the host, use the server's LAN IP — never use localhost (that points inside Huntarr's own container)
• Make sure the *arr app has no Base URL set, or include it in the URL: http://192.168.1.100:8989/sonarr
• Try the Test Connection button — the error message usually indicates exactly what's wrong

Can I connect multiple instances of the same app?

Yes. Huntarr fully supports multiple instances of the same app type — for example, separate Sonarr instances for 1080p and 4K. Each instance gets its own independent schedule, caps, and settings. Add each one separately under Apps → 3rd Party Apps.

Hunting

Hunts run but nothing is found

• Verify your *arr app has at least one working indexer — test it directly in the *arr app first
• Check that the media is monitored in the *arr app (unmonitored items won't be searched)
• For movies, check the Minimum Availability setting — if set to "Released," pre-release content won't be searched
• Try searching manually in the *arr app — if it doesn't find anything there, Huntarr won't either (they use the same API)
• Check the Huntarr logs (System → Logs) for specific error messages from that hunt cycle

Hunts are too aggressive / I got rate-limited by my indexer

• Reduce the cap per cycle — start at 1–3 items
• Increase the schedule interval to 30–60 minutes minimum
• Use per-instance schedules and stagger them by 15–30 minutes so multiple instances don't hit indexers simultaneously
• Check your indexer's rate limit policy — most allow 100–200 API calls/day per account

Hunt schedules aren't running

• Verify the schedule is enabled in Settings → Scheduling
• Check that the app instance is connected and enabled under Apps
• Review System → Logs for any error messages from the scheduler
• Restart Huntarr if schedules appear stuck: docker restart huntarr

Movie Hunt & TV Hunt

Movie Hunt/TV Hunt is not finding releases

• Verify you have at least one indexer configured and passing its connection test
• Check that a download client is configured and reachable
• Ensure the movie/show's minimum availability allows searching (avoid "Announced" for Usenet — content may not exist yet)
• Check that a quality profile is assigned — without one, Movie Hunt won't know what to grab
• Review System → Logs for search activity and errors

Downloads aren't completing / items stuck as "Requested"

• Verify your download client (SABnzbd, NZBGet, NZB Hunt, etc.) is running and accessible
• Check the download client's own queue/logs for error messages
• Ensure the download category configured in Movie Hunt exists in your download client
• Check available disk space on the download volume

NZB Hunt

NZB Hunt downloads fail immediately

• Test your NNTP server connection: go to NZB Hunt → Settings → Servers and click Test
• Verify credentials (username, password, host, port) are correct
• Try reducing the connection count to 5 to rule out a server connection limit
• Check that SSL is enabled and port 563 is used (or 119 for plain — not recommended)

Downloads fail with "too many missing articles"

This means the NZB file references Usenet posts that no longer exist on your provider's servers — a retention issue. The content is older than your provider's retention window or your provider has incomplete coverage. Solutions:

• Switch to a provider with longer retention (some offer 4,000+ days)
• Add a second provider as a backup server in NZB Hunt — gaps from the primary are filled from the backup
• Use a different indexer to find a fresher NZB for the same release

NZB Hunt aborted a download — "encrypted RAR"

This is expected. By default (new installs), NZB Hunt aborts password-protected RAR archives. Password-protected releases are generally poor-quality or scam releases on Usenet. To change this:

• Go to NZB Hunt → Settings → Processing
• Change Encrypted RAR Action from "Abort" to "Pause"
• Pausing lets you inspect and decide manually; aborting removes it automatically

/downloads isn't created or NZB Hunt can't write files

• Ensure /downloads is mapped in your Docker configuration — it will not be auto-created otherwise
• Verify the host path is writable by the PUID/PGID set in the container
• NZB Hunt creates /downloads/incomplete and /downloads/complete itself on first use — you just need the parent path to exist and be writable

Requestarr

Can other users (family, friends) use Requestarr?

Yes — Requestarr supports multiple user accounts. Invite others by creating accounts under Settings → User Account → Users. Invited users log in at your Huntarr URL and see only the Requests section; they cannot access hunt controls, app settings, or any admin area.

What is a Bundle and when should I use one?

A Bundle groups multiple instances so a single request goes to all of them simultaneously. Example: a "Movies" bundle with 1080p Radarr and 4K Radarr — one request, both receive it. If a member fails (offline, misconfigured), the failure is logged and the cascade continues to remaining members.

A request was approved but nothing appeared in the library

• Verify the target instance is connected and responding (test under Apps → 3rd Party Apps)
• Check System → Logs for errors that occurred during request processing
• For bundles, check whether the primary instance succeeded — bundle member results are logged separately
• Confirm the instance has a working indexer and download client configured

Database & Backup

Huntarr lost my settings after restart

• Ensure the /config volume is mapped to a persistent host path — not an anonymous Docker volume
• Update to the latest version (this was fixed in earlier builds)
• Enable automatic backups in Settings → Backup & Restore as insurance going forward

How do I migrate to a new server?

1. Create a manual backup: Settings → Backup & Restore → Create Backup Now
2. Download the backup file to your local machine
3. Install Huntarr on the new server
4. Complete the Setup Wizard to create your admin account
5. Go to Settings → Backup & Restore → Upload and restore the backup
6. All instances, schedules, notification settings, and app configurations are restored