Common Issues & Solutions¶

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

Contents¶

• Connection Issues
• Torrent Processing Issues
• Search Issues
• Import Issues
• Performance Issues
• Disk Space Issues
• Configuration Issues
• WebUI Issues
• Logging Issues
• Getting More Help
• Error Reference
• Related Documentation

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 qBitrr after config change

Arr Instance Connection Failures¶

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

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 qBitrr are in the same Docker network, use service name:

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

Torrent Processing Issues¶

Torrents Not Being Monitored¶

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

Common Cause: Category Mismatch

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

How to Fix:

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

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

5. Check qBitrr 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 qBitrr

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: qBitrr 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 qBitrr 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. "Downloading metadata" (metaDL) is handled by the same StalledDelay setting

9. Enable re-search for stalled:

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

10. Check logs for stall detection:

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

Search Issues¶

Automated Searches Not Running¶

Symptom: qBitrr 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. HTTP 415 / unmapped Arr errors during Sonarr year search:

Older builds could log Search loop crashed unexpectedly ... Exception: (415, '') while loading years (episode.get for SearchByYear). pyarr does not map HTTP 415 to a typed error, so the worker treated it as fatal.

qBitrr now backs off for 5 minutes on those Arr HTTP failures instead of exiting, and skips a single series that fails episode.get so the rest of the library still searches. A connectivity outage during episode fetches is raised immediately (not retried per series). If every series fails, DB ingest also backs off instead of marking the refresh complete.

An empty 415 body often comes from a reverse proxy or WAF on GET /api/v3/episode. Test that URL with X-Api-Key from the same network as qBitrr. Workaround: set SearchByYear = false for that Sonarr section.

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: qBitrr searches but Arr reports "No results"¶

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

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. qBitrr'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 qBitrr
   

2. Check file permissions:

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

3. Enable instant import:

4. qBitrr 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 qBitrr 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¶

qBitrr 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 qBitrr:
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 qBitrr 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. qBitrr can't write to config file

3. Solution: Fix permissions:

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

4. Invalid syntax:

5. qBitrr detected invalid TOML and regenerated defaults

6. Solution: Restore from backup, fix syntax errors

7. Config migration:

8. qBitrr 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/health
   

3. Check firewall:

   # Allow port 6969
   sudo ufw allow 6969/tcp
   

4. Docker port mapping:

   services:
     qbitrr:
       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 qBitrr

6. Access logs without WebUI:

   # Docker
   docker logs qbitrr
   
   # 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 qbitrr:qbitrr /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 qBitrr 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/qBitrr/issues

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

Error Reference¶

Exception Hierarchy¶

qBitrr uses a custom exception hierarchy for error handling:

qBitManagerError (base)
├── UnhandledError
├── ConfigException
├── ArrManagerException
│   └── RestartLoopException
├── SkipException
├── RequireConfigValue
├── NoConnectionrException
└── DelayLoopException

Python Exceptions¶

Exit Codes¶

HTTP Status Codes¶

qBitrr WebUI API returns standard HTTP status codes:

Related Documentation¶

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