Frequently Asked Questions

Huntarr automatically searches for missing content in your Sonarr, Radarr, Lidarr, Readarr, and Whisparr applications. Think of it as a "search assistant" that runs constantly to find missing episodes, movies, music, and books. Prerequisites:

• At least one *arr application (Sonarr, Radarr, etc.) already installed and working
• Indexers configured in your *arr apps
• Download client (qBittorrent, Deluge, etc.) configured

Docker is strongly recommended for all platforms. Here's the simplest setup:

docker run -d --name huntarr \
  --restart unless-stopped \
  -p 9705:9705 \
  -v /path/to/huntarr/config:/config \
  -e TZ=America/New_York \
  huntarr/huntarr:latest

After installation:

1. Open http://YOUR_IP:9705
2. Create admin account
3. Add your *arr applications in Settings

This is normal for open-source software that isn't Microsoft-signed. The installer is safe, but Windows shows warnings. To install on Windows:

1. When Windows SmartScreen appears, click "More info"
2. Click "Run anyway" at the bottom
3. Allow through Windows Firewall when prompted

Common causes and solutions:

• Wrong IP: Try http://YOUR_SERVER_IP:9705 instead of localhost
• Port conflict: Another app is using port 9705
• Firewall: Port 9705 is blocked
• Container not running: Check with docker ps | grep huntarr

Quick troubleshooting:

# Check if Huntarr is running
docker ps | grep huntarr

# Check the logs
docker logs huntarr

# Restart if needed
docker restart huntarr

This means Huntarr can't reach your *arr applications. Check these in order:

1. URL format: Use http://IP:PORT (e.g., http://192.168.1.10:8989)
2. Remove trailing slash: Don't use http://IP:PORT/
3. Test manually: Can you access the *arr app in your browser?
4. Network access: Can Huntarr's container reach your *arr apps?

Quick test:

# Test from inside Huntarr container
docker exec -it huntarr wget -qO- http://YOUR_ARR_IP:PORT/api/v3/system/status

Your API key is wrong or missing. To get the correct API key:

1. Open your *arr application (Sonarr, Radarr, etc.)
2. Go to Settings → General
3. Look for "API Key" section
4. Copy the entire key (usually 32 characters)
5. Paste it exactly into Huntarr settings

This is usually a Docker volume permission issue. Fix permissions:

# Stop Huntarr
docker stop huntarr

# Fix ownership (replace with your actual path)
sudo chown -R 1000:1000 /path/to/huntarr/config

# Start Huntarr
docker start huntarr

This usually means your content is not marked as "Monitored" in your *arr apps. Check this:

1. Open your *arr application
2. Look at your movies/shows/music
3. Ensure items are marked as "Monitored" (usually a toggle or checkbox)
4. Check that you have missing content (red icons in *arr apps)

Check the logs first:

docker logs huntarr

Common causes:

• Permission issues: Config directory not writable
• Port conflict: Port 9705 already in use
• Memory limits: Not enough RAM allocated
• Corrupted config: Bad configuration files

Reset if needed:

# Stop and remove container
docker stop huntarr && docker rm huntarr

# Clear config (backup first!)
rm -rf /path/to/huntarr/config/*

# Recreate container
docker run -d --name huntarr ...

This is a Docker networking issue. Solution 1 - Use host networking:

docker run -d --name huntarr \
  --network host \
  --restart unless-stopped \
  -v /path/to/huntarr/config:/config \
  huntarr/huntarr:latest

Solution 2 - Use Docker bridge with correct IPs:

• Find your host's Docker IP: ip route show default
• Use that IP in Huntarr settings instead of localhost
• Example: http://172.17.0.1:8989 instead of http://localhost:8989

Here's a complete docker-compose.yml example:

version: '3.8'
services:
  huntarr:
    image: huntarr/huntarr:latest
    container_name: huntarr
    restart: unless-stopped
    ports:
      - "9705:9705"
    volumes:
      - ./huntarr-config:/config
    environment:
      - TZ=America/New_York
      - PUID=1000
      - PGID=1000

Run with:

docker-compose up -d

This indicates a file permission problem. Fix it:

1. Stop Huntarr: docker stop huntarr
2. Check directory ownership: ls -la /path/to/huntarr/
3. Fix permissions: sudo chown -R 1000:1000 /path/to/huntarr/
4. Start Huntarr: docker start huntarr

Usually a browser caching issue or JavaScript error. Try these in order:

1. Hard refresh: Ctrl+F5 (Windows) or Cmd+Shift+R (Mac)
2. Clear browser cache for the Huntarr site
3. Try incognito/private mode
4. Try a different browser
5. Check browser console for JavaScript errors (F12)

Checklist to verify:

1. Content is monitored: Check your *arr apps - items must be marked "Monitored"
2. Content is actually missing: Look for red indicators in your *arr apps
3. Indexers are working: Test manual search in your *arr apps
4. Download queue isn't full: Check your download client
5. Huntarr settings: Verify hunt missing/upgrade limits aren't 0

Check Huntarr's processing: Look at the dashboard counters - they should increase over time if content is being processed.

Most common reasons:

• No missing content: Everything is already downloaded
• Content not monitored: Items aren't marked as monitored in *arr apps
• Future releases: "Skip Future Episodes/Movies" is enabled and content isn't released yet
• Download queue full: Queue size exceeds your minimum threshold
• API limits reached: Hourly API cap is hit

Quick check:

1. Go to your Sonarr/Radarr wanted pages
2. Verify there are missing items shown
3. Check if they're marked as "Monitored"

Optimize your settings:

• Increase sleep duration: Use 15+ minutes between cycles
• Reduce batch sizes: Lower "Hunt Missing" and "Hunt Upgrades" numbers
• Set API limits: Use reasonable hourly caps (20-50 per app)
• Check indexers: Slow indexers can cause timeouts

Reduce resource usage:

• Increase sleep duration: 20-30 minutes between cycles
• Lower batch sizes: Process fewer items per cycle
• Set stricter API limits: Prevent overloading
• Enable "Skip Future Items": Avoid unnecessary processing

Protect your indexers:

1. Set hourly API caps: 20-50 requests per hour per app
2. Increase sleep duration: 20+ minutes between cycles
3. Lower batch sizes: 5-10 missing items, 2-5 upgrades per cycle
4. Enable monitored-only: Don't search for unmonitored content

Reset authentication:

# Stop Huntarr
docker stop huntarr

# Remove credentials file
                # Credentials are now stored in the database at /config/huntarr.db (Docker) or /path/to/huntarr/data/huntarr.db (local)
                # To reset credentials, delete the database file or use the web interface

# Start Huntarr
docker start huntarr

Now you can access the web interface and create a new admin account.

Same solution as password reset - remove the credentials file:

# Credentials are now stored in the database at /config/huntarr.db (Docker) or /path/to/huntarr/data/huntarr.db (local)
# To reset credentials, delete the database file or use the web interface

This will reset both password and 2FA settings.

Generally not recommended unless you need remote access. If you must expose it:

• Enable strong authentication
• Use 2FA
• Use a reverse proxy with SSL
• Consider VPN access instead