Common Issues & Solutions¶

This page covers the most frequently encountered issues with Torrentarr and their solutions.

Connection Issues¶

qBittorrent Connection Failures¶

Symptom: "Connection refused" or "Connection timeout"¶

Possible Causes:

• qBittorrent is not running
• Wrong Host or Port in config
• Firewall blocking connection
• qBittorrent Web UI is disabled

Solutions:

1. Verify qBittorrent is running:

   # Check if qBittorrent process is active
   ps aux | grep qbittorrent
   

2. Check Web UI is enabled:

3. Open qBittorrent
4. Go to Tools → Options → Web UI
5. Ensure "Web User Interface (Remote control)" is checked

6. Note the IP address and port

7. Test connection manually:

   # Replace with your actual values
   curl -i http://localhost:8080/api/v2/app/version
   

   Expected: HTTP 200 response with version number

8. Check firewall rules:

   # Linux (ufw)
   sudo ufw allow 8080/tcp
   
   # Linux (firewalld)
   sudo firewall-cmd --add-port=8080/tcp --permanent
   sudo firewall-cmd --reload
   

9. Docker: Use correct host:

10. Same network: Use container name (e.g., qbittorrent)
11. Different network: Use host IP or host.docker.internal (macOS/Windows)

Symptom: "Invalid username or password"¶

Possible Causes:

• Wrong credentials in config
• Authentication bypass enabled but credentials still provided
• Recent password change not reflected in config

Solutions:

1. Verify credentials:
2. Open qBittorrent Web UI manually
3. Try logging in with the same credentials from config.toml

4. If login fails, update credentials in qBittorrent settings

5. Check authentication bypass:

6. In qBittorrent: Tools → Options → Web UI → Authentication

7. If "Bypass authentication for clients on localhost" is enabled:

   [qBit]
   UserName = ""
   Password = ""
   

8. Test login manually:

   curl -i --header "Referer: http://localhost:8080" \
     --data "username=admin&password=yourpass" \
     http://localhost:8080/api/v2/auth/login
   

   Expected: Ok. response

Symptom: Connection errors or API failures¶

Possible Causes:

• Incorrect host or port configuration
• Authentication credentials are wrong
• qBittorrent WebUI is not enabled
• Network connectivity issues

Solutions:

1. Verify qBittorrent is running and accessible:
2. Open qBittorrent WebUI in a browser: http://localhost:8080

3. Check Tools → Options → Web UI is enabled

4. Check configuration:

   [qBit]
   Host = "localhost"
   Port = 8080
   UserName = "admin"
   Password = "password"
   

5. Test connectivity manually:

   curl http://localhost:8080/api/v2/app/version
   

6. Restart Torrentarr after config change

Arr Instance Connection Failures¶

Symptom: "Connection refused" when connecting to Radarr/Sonarr/Lidarr¶

Solutions:

1. Test Arr API manually:

   # Radarr
   curl -H "X-Api-Key: your-api-key" http://localhost:7878/api/v3/system/status
   
   # Sonarr
   curl -H "X-Api-Key: your-api-key" http://localhost:8989/api/v3/system/status
   
   # Lidarr
   curl -H "X-Api-Key: your-api-key" http://localhost:8686/api/v1/system/status
   

2. Verify URI format:

   # ✅ Correct
   URI = "http://localhost:7878"
   
   # ❌ Incorrect (missing http://)
   URI = "localhost:7878"
   
   # ❌ Incorrect (trailing slash)
   URI = "http://localhost:7878/"
   

3. Check API key:

4. Copy API key from Arr instance: Settings → General → Security
5. Paste into config.toml (no extra spaces!)

6. API keys are case-sensitive

7. Docker networking:

8. If Arr and Torrentarr are in the same Docker network, use service name:

   URI = "http://radarr:7878"  # Not "localhost"
   

Torrent Processing Issues¶

Torrents Not Being Monitored¶

Symptom: Torrentarr starts but doesn't process any torrents¶

Common Cause: Category Mismatch

The #1 reason Torrentarr doesn't process torrents is mismatched categories.

How to Fix:

1. Check Arr download client category:
2. Radarr/Sonarr/Lidarr → Settings → Download Clients
3. Click your qBittorrent client

4. Note the Category field (e.g., radarr-movies)

5. Check Torrentarr config:

   [Radarr-Movies]
   Category = "radarr-movies"  # Must EXACTLY match!
   

6. Check existing torrents in qBittorrent:

7. Open qBittorrent
8. Look at the Category column for your Arr torrents

9. Categories must match between qBittorrent, Arr, and Torrentarr

10. Enable debug logging to verify:

    [Settings]
    ConsoleLevel = "DEBUG"
    

    Look for: Processing category: radarr-movies in logs

Other Causes:

• Missing tags: Arr instances need to tag torrents. Check Settings.Tagless if you don't use tags.
• Instance disabled: Verify Managed = true in the Arr section
• qBit disabled: Check [qBit] Disabled = false

Torrents Instantly Marked as Failed¶

Symptom: Torrents are added but immediately fail¶

Possible Causes:

1. Too young: Torrentarr ignores torrents younger than IgnoreTorrentsYoungerThan (default: 180 seconds)

Solution: Wait 3 minutes, or lower the value:

[Settings]
IgnoreTorrentsYoungerThan = 60  # 1 minute

1. File extension not allowed:

Solution: Add missing extensions to allowlist:

[Radarr-Movies.Torrent]
FileExtensionAllowlist = [".mp4", ".mkv", ".avi", ".!qB", ".parts"]

1. FFprobe validation failure:

Solution: Check FFprobe logs or disable validation temporarily

1. ETA exceeds maximum:

Solution: Increase or disable MaxETA:

[Radarr-Movies.Torrent]
MaximumETA = -1  # Disable
# Or increase: MaximumETA = 86400  # 24 hours

Stalled Torrents Not Being Handled¶

Symptom: Torrents stall but Torrentarr doesn't remove them¶

Solutions:

1. Check stalled delay setting:

   [Radarr-Movies.Torrent]
   StalledDelay = 15  # Wait 15 minutes before removal
   

2. -1 = Disabled (never remove stalled)
3. 0 = Immediate removal

4. >0 = Wait N minutes before removal

5. Verify torrent is actually stalled:

6. In qBittorrent, check torrent status

7. "Stalled" means no peers and no progress

8. Enable re-search for stalled:

   [Radarr-Movies.Torrent]
   ReSearchStalled = true  # Search before removing
   

9. Check logs for stall detection:

   tail -f ~/logs/Radarr-Movies.log | grep -i stall
   

Search Issues¶

Automated Searches Not Running¶

Symptom: Torrentarr runs but doesn't search for missing media¶

Root Cause: SearchMissing is the master switch for all search features.

Solutions:

1. Enable SearchMissing (required):

   [Radarr-Movies.EntrySearch]
   SearchMissing = true  # REQUIRED - master switch for all search features
   

Important: DoUpgradeSearch, QualityUnmetSearch, CustomFormatUnmetSearch, and request processing (Overseerr/Ombi) will ONLY work if SearchMissing is enabled.

1. Check search loop startup in logs:

   grep "Search loop starting\|Search loop initialized" ~/logs/Radarr-Movies.log
   

You should see:

Search loop starting for Radarr-Movies (SearchMissing=True, ...)
Search loop initialized successfully, entering main loop

1. If search loop crashes or exits unexpectedly:

   grep "Search loop crashed\|Search loop terminated" ~/logs/Radarr-Movies.log
   

If you see "Search loop crashed", check the full traceback above that line.

1. Common mistake - SearchLoopDelay:

Note: SearchLoopDelay controls the delay between individual searches in a batch, not whether searches run.

[Settings]
SearchLoopDelay = -1  # -1 = uses default 30s between each search

1. Verify Arr has missing media:
2. Open Radarr/Sonarr → Wanted → Missing

3. If empty, there's nothing to search for

4. Check indexer connectivity:

5. In Arr instance: System → Status
6. Ensure indexers are enabled and reachable

Overseerr/Ombi Requests Not Processing¶

Symptom: User requests aren't being searched¶

Solutions:

1. Enable request processing:

   [Radarr-Movies.EntrySearch.Overseerr]
   SearchOverseerrRequests = true
   

2. Verify connection details:

   OverseerrURI = "http://localhost:5055"  # Correct URI?
   OverseerrAPIKey = "your-api-key"         # Valid API key?
   

3. Test API manually:

   curl -H "X-Api-Key: your-api-key" \
     http://localhost:5055/api/v1/request
   

4. Check approval status:

   ApprovedOnly = true  # Only processes approved requests
   

5. If true, make sure requests are approved in Overseerr

6. Set to false to process all requests

7. Verify 4K instance flag:

   Is4K = true  # For 4K Radarr instances
   

   Must match your Overseerr configuration

Searches Trigger But Find Nothing¶

Symptom: Torrentarr searches but Arr reports "No results"¶

This is usually an Arr/indexer issue, not Torrentarr.

Solutions:

1. Test search in Arr directly:
2. Go to Wanted → Missing
3. Click Search for a specific item

4. Check if Arr finds results

5. Check indexer configuration:

6. Settings → Indexers
7. Test each indexer

8. Review indexer logs for errors

9. Check indexer rate limits:

10. Some indexers have API rate limits
11. Torrentarr's searches count against your limit

12. Review indexer stats/logs

13. Verify quality profile settings:

14. Overly strict quality profiles may filter out all results

15. Temporarily lower standards to test

16. Check custom format scores:

17. If using custom formats, high minimum scores may block releases
18. Temporarily disable CF scoring to test

Import Issues¶

Files Not Importing After Download¶

Symptom: Torrent completes but Arr doesn't import files¶

Solutions:

1. Check path mapping:
2. qBittorrent's save path must be accessible to Arr
3. Common Docker issue: mismatched volume paths

Example (Docker):

qbittorrent:
  volumes:
    - /mnt/data/torrents:/downloads

radarr:
  volumes:
    - /mnt/data/torrents:/downloads  # Must match!

1. Verify CompletedDownloadFolder:

   [Settings]
   CompletedDownloadFolder = "/downloads"  # Must be accessible to Torrentarr
   

2. Check file permissions:

   # All files must be readable by Arr instance
   ls -l /path/to/completed/downloads
   

3. Enable instant import:

4. Torrentarr triggers instant imports automatically

5. Check logs for import triggers:

   tail -f ~/logs/Main.log | grep -i import
   

6. Manual import test in Arr:

7. Activity → Queue
8. Click Manual Import for the download
9. Check error messages

Import Succeeds But Quality Is Wrong¶

Symptom: Files import but don't match expected quality¶

This is usually an Arr quality profile issue.

Solutions:

1. Review quality profile:
2. Settings → Profiles
3. Check which qualities are allowed

4. Verify upgrade conditions

5. Check custom formats:

6. Settings → Custom Formats
7. Review scoring and minimum scores

8. Ensure downloaded file meets requirements

9. Use quality upgrade search:

   [Radarr-Movies.EntrySearch]
   DoUpgradeSearch = true
   QualityUnmetSearch = true
   

10. Enable temp profile switching:

    UseTempForMissing = true
    QualityProfileMappings = { "Ultra-HD" = "HD-1080p" }
    

    This grabs something initially, then upgrades later

Performance Issues¶

High CPU Usage¶

Possible Causes:

1. Too frequent loop processing:

   [Settings]
   LoopSleepTimer = 1  # Very aggressive
   

   Solution: Increase to 5-10 seconds:

   LoopSleepTimer = 5
   

2. Too many concurrent searches:

   [Radarr-Movies.EntrySearch]
   SearchLimit = 10  # Too high
   

   Solution: Lower to 3-5:

   SearchLimit = 3
   

3. Database locked:

4. Multiple Torrentarr instances accessing same database
5. Solution: Use separate config directories for multiple instances

High Memory Usage¶

Possible Causes:

1. Large torrent libraries:
2. Processing thousands of torrents uses significant RAM

3. Solution: Split libraries across multiple Arr instances

4. Extensive logging:

   [Settings]
   ConsoleLevel = "TRACE"  # Very verbose
   

   Solution: Use INFO or WARNING:

   ConsoleLevel = "INFO"
   

5. WebUI live updates:

   [WebUI]
   LiveArr = true  # Increases memory usage
   

   Solution: Disable if not needed:

   LiveArr = false
   

Disk Space Issues¶

Torrentarr Doesn't Pause Torrents When Disk Is Full¶

Solutions:

1. Enable AutoPauseResume:

   [Settings]
   AutoPauseResume = true
   

2. Set FreeSpace threshold:

   FreeSpace = "50G"  # Pause when <50GB free
   

   Supported units: K (KB), M (MB), G (GB), T (TB)

3. Set FreeSpaceFolder:

   FreeSpaceFolder = "/downloads"  # Path to check
   

   Must be the mount point or directory to monitor

4. Verify path is correct:

   df -h /downloads  # Check available space
   

Torrents Removed But Disk Space Not Freed¶

Possible Causes:

1. Files copied, not moved:

   [Radarr-Movies]
   importMode = "Copy"  # Leaves files in download folder
   

   Solution: Use Move to free space:

   importMode = "Move"
   

2. Seeding torrents:

3. Files remain until seeding goals met

4. Solution: Adjust seeding limits:

   [Radarr-Movies.Torrent.SeedingMode]
   MaxUploadRatio = 1.0  # Lower ratio
   MaxSeedingTime = 86400  # 1 day
   RemoveTorrent = 1  # Remove when ratio met
   

5. MaximumDeletablePercentage protection:

   [Radarr-Movies.Torrent]
   MaximumDeletablePercentage = 0.99  # Won't delete nearly-complete
   

Configuration Issues¶

Config Changes Not Taking Effect¶

Solutions:

1. Restart Torrentarr:
2. Config is loaded only at startup

3. Changes require restart to apply

4. Check config syntax:

5. TOML syntax errors prevent loading

6. Test with online TOML validator

7. Check config location:

8. Docker: /config/config.toml
9. Native: ~/config/config.toml

10. Verify Torrentarr is reading the correct file

11. Enable debug logging:

    [Settings]
    ConsoleLevel = "DEBUG"
    

    Look for config loading messages

Config File Regenerates or Resets¶

Possible Causes:

1. File permissions:
2. Torrentarr can't write to config file

3. Solution: Fix permissions:

   chmod 644 ~/config/config.toml
   chown torrentarr:torrentarr ~/config/config.toml
   

4. Invalid syntax:

5. Torrentarr detected invalid TOML and regenerated defaults

6. Solution: Restore from backup, fix syntax errors

7. Config migration:

8. Torrentarr auto-migrates old configs
9. Check logs for migration messages
10. Backups created at /config/config.toml.backup_*

WebUI Issues¶

Can't Access WebUI¶

Solutions:

1. Check WebUI settings:

   [WebUI]
   Host = "0.0.0.0"  # Listen on all interfaces
   Port = 6969        # Default port
   

2. Test connection:

   curl http://localhost:6969/api/health
   

3. Check firewall:

   # Allow port 6969
   sudo ufw allow 6969/tcp
   

4. Docker port mapping:

   services:
     torrentarr:
       ports:
         - "6969:6969"  # host:container
   

WebUI Requires Token But I Don't Have One¶

Solution:

1. Token is optional:

   [WebUI]
   Token = ""  # Empty = no authentication required
   

2. If Token is set but lost:

3. Edit /config/config.toml
4. Set Token = ""

5. Restart Torrentarr

6. Access logs without WebUI:

   # Docker
   docker logs torrentarr
   
   # Native
   tail -f ~/logs/Main.log
   

Logging Issues¶

Logs Not Being Created¶

Solutions:

1. Enable logging:

   [Settings]
   Logging = true
   

2. Check log directory:

3. Docker: /config/logs/
4. Native: ~/logs/

5. Verify directory exists and is writable

6. Check permissions:

   chmod 755 /config/logs
   chown -R torrentarr:torrentarr /config/logs
   

Logs Too Verbose or Too Quiet¶

Adjust logging level:

[Settings]
ConsoleLevel = "INFO"  # CRITICAL, ERROR, WARNING, NOTICE, INFO, DEBUG, TRACE

Recommendations:

• Production: INFO or WARNING
• Troubleshooting: DEBUG
• Development: TRACE (very verbose!)

Getting More Help¶

If your issue isn't covered here:

1. Enable debug logging:

   [Settings]
   ConsoleLevel = "DEBUG"
   

2. Collect relevant logs:

3. Main.log – Core Torrentarr operations
4. Radarr-Movies.log – Arr-specific processing

5. WebUI.log – WebUI-related issues

6. Check FAQ: Frequently Asked Questions

7. Report issue on GitHub: github.com/Feramance/Torrentarr/issues

8. Include config (redact API keys!)
9. Include relevant log excerpts
10. Describe expected vs. actual behavior

Error Reference¶

Exception Hierarchy¶

Torrentarr uses a custom exception hierarchy for error handling (C# types in Torrentarr.Core / Infrastructure). Base and derived types represent configuration, connection, and Arr-related failures.

Exit Codes¶

HTTP Status Codes¶

Torrentarr WebUI API returns standard HTTP status codes:

Related Documentation¶

• Docker Troubleshooting
• qBittorrent Configuration
• Radarr Configuration
• Sonarr Configuration