FAQ & Troubleshooting

Answers to common questions and solutions to frequent issues.

General

What is Huntarr?

Huntarr is an automated media hunting companion for the *arr stack (Sonarr, Radarr, Lidarr, Readarr, Whisparr). It continuously searches for missing media and upgrades existing files to better quality. It also includes Movie Hunt (standalone movie grabber), NZB Hunt (Usenet search), and Requests (media requests for the person running Huntarr, not for other users).

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

The *arr apps have their own search capabilities, but they only search when you manually trigger it or when new items are added. Huntarr runs on a schedule, continuously re-trying searches for items that haven't been found yet, and looking for quality upgrades.

Does Huntarr replace Sonarr/Radarr?

No. Huntarr works alongside your *arr apps. It uses their APIs to trigger searches. You still need Sonarr, Radarr, etc. for managing your library. The exception is Movie Hunt, which is a standalone movie grabber.

What ports does Huntarr use?

By default, Huntarr runs on port 9705. You can change this in Settings > Main or via the HUNTARR_PORT environment variable.

Installation

Docker container won't start

• Check that port 9705 isn't already in use
• Verify your volume mappings exist and are writable
• Check container logs: docker logs huntarr
• Ensure the image is up-to-date: docker pull huntarr/huntarr:latest

"Permission denied" errors

• Ensure the /config directory is writable by the container
• Check file ownership: the container runs as root by default
• On Unraid, ensure the template has correct path mappings

Huntarr is unreachable

• Verify the container is running: docker ps | grep huntarr
• Check the port mapping in your Docker configuration
• Try accessing directly: http://your-server-ip:9705
• Check firewall rules

App Connections

"API key invalid" error

• Re-copy the API key from your *arr app (Settings > General > Security)
• Ensure there are no extra spaces or characters
• Verify the URL includes the correct port
• Test the URL directly in your browser (should show the *arr web UI)

Can't connect to *arr app

• Verify the app is running and accessible
• Use the internal Docker network name if both are in Docker (e.g., http://sonarr:8989)
• Check that you're using the correct port
• Try the IP address instead of hostname

Multiple instances of the same app

Yes, Huntarr fully supports multiple instances. Add each instance separately with its own URL and API key. You can configure different schedules and settings per instance.

Hunting

Hunts run but nothing is found

• Check that your *arr app has working indexers
• Verify the media is monitored in the *arr app
• For movies, check the Minimum Availability setting
• Try searching manually in the *arr app — if it doesn't find anything there, Huntarr won't either
• Increase caps gradually; some media takes multiple search attempts

Hunts are too aggressive / indexer bans

• Reduce the cap per cycle (start with 1-3)
• Increase the schedule interval (30-60 minutes minimum)
• Use per-instance schedules to stagger load
• Check your indexer's rate limits

Hunt schedules aren't running

• Verify the schedule is enabled in Settings > Scheduling
• Check that the app instance is connected and enabled
• Review logs for any error messages
• Restart Huntarr if schedules seem stuck

Movie Hunt

Movie Hunt isn't finding movies

• Verify you have at least one indexer configured and working
• Check that a download client is configured
• Ensure the movie's minimum availability allows searching
• Try searching directly in NZB Hunt to test indexer connectivity

Downloads aren't completing

• Verify your download client is running and accessible
• Check the download client's logs for errors
• Ensure the download category exists in your client
• Check available disk space

Database & Backup

Huntarr lost my settings after restart

• This was a known issue that has been fixed in recent versions
• Update to the latest version
• Enable automatic backups as insurance
• Check that your /config volume is properly mounted and persistent

How to migrate to a new server

1. Create a backup in Settings > Backup & Restore
2. Copy the backup file to the new server
3. Install Huntarr on the new server
4. Complete the setup wizard
5. Upload and restore the backup