Health Monitoring¶

qBitrr continuously monitors the health of your torrents, detecting and handling issues automatically to ensure smooth media downloads.

Overview¶

Health monitoring is one of qBitrr's core features. It watches all torrents managed by your Arr instances and takes automatic action when problems are detected.

What Gets Monitored¶

• Download speed - Detects slow or stalled torrents
• Completion progress - Tracks download percentage
• ETA (Estimated Time of Arrival) - Predicts when downloads will finish
• Tracker status - Monitors tracker announces and errors
• File validation - Uses FFprobe to verify media files
• Import status - Tracks Arr instance import progress

Torrent Health States¶

stateDiagram-v2
    [*] --> Detected: Torrent added to qBittorrent

    Detected --> Downloading: Peers found, downloading
    Detected --> Stalled: No peers, speed = 0

    Downloading --> Healthy: Speed good, ETA acceptable
    Downloading --> Slow: Speed low, ETA > MaximumETA
    Downloading --> Stalled: Lost all peers

    Healthy --> Completed: 100% downloaded
    Slow --> Completed: Eventually finishes

    Stalled --> Downloading: Peers reconnect
    Stalled --> Failed: StalledDelay exceeded

    Slow --> Failed: DoNotRemoveSlow=false && ETA too high

    Completed --> Validating: FFprobe check

    Validating --> Importing: File valid
    Validating --> Failed: Corruption detected

    Importing --> Imported: Arr import successful
    Importing --> Failed: Import failed

    Imported --> Seeding: SeedingMode enabled
    Imported --> Cleanup: SeedingMode disabled

    Seeding --> Cleanup: Seed requirements met

    Failed --> Blacklisted: Add to Arr blacklist
    Blacklisted --> ReSearch: ReSearch enabled
    Blacklisted --> Removed: ReSearch disabled

    Cleanup --> Removed: Delete from qBittorrent
    ReSearch --> Removed: Trigger new search

    Removed --> [*]: Torrent lifecycle complete

    note right of Healthy
        Green status
        Normal operation
    end note

    note right of Slow
        Yellow status
        Monitored closely
    end note

    note right of Stalled
        Orange status
        Grace period active
    end note

    note right of Failed
        Red status
        Blacklist triggered
    end note

State Descriptions:

• Detected - qBitrr discovers torrent in qBittorrent
• Downloading - Active download in progress
• Healthy - Meeting all health thresholds
• Slow - Download speed below expectations
• Stalled - No progress, waiting for StalledDelay
• Completed - 100% downloaded, awaiting validation
• Validating - FFprobe checking media files
• Importing - Arr instance importing files
• Imported - Successfully imported to media library
• Seeding - Meeting seeding requirements
• Failed - Health check failed, blacklisting
• Blacklisted - Added to Arr blacklist
• ReSearch - Triggering new search for alternative
• Cleanup - Deleting from qBittorrent
• Removed - Lifecycle complete

Stalled Torrent Detection¶

What is a Stalled Torrent?¶

A torrent is considered "stalled" when:

• ✅ Download speed is 0 B/s
• ✅ No peers available
• ✅ Stuck at same completion percentage
• ✅ Exceeds configured StalledDelay time

Configuration¶

[Radarr-Movies.Torrent]
# Maximum stalled time before action (minutes)
StalledDelay = 15  # Wait 15 minutes before marking as stalled

# Actions for stalled torrents
ReSearchStalled = false  # false = remove only, true = search then remove

Stalled Delay Values¶

Recommended Settings:

• Movies/TV: 15 minutes (default)
• Music: 30 minutes (slower trackers)
• Private Trackers: 30-45 minutes (conservative)
• Rare Content: 60 minutes (very patient)

Stalled Torrent Workflow¶

graph TD
    A[Torrent Detected as Stalled] --> B{ReSearchStalled?}
    B -->|true| C[Trigger Search in Arr]
    B -->|false| D[Mark as Failed]
    C --> E[Blacklist Release]
    D --> E
    E --> F[Remove Torrent]
    F --> G[Notify Arr Instance]
    G --> H{ReSearch Enabled?}
    H -->|true| I[Arr Searches for New Release]
    H -->|false| J[End]

Actions taken:

1. ⏰ qBitrr waits StalledDelay minutes
2. 🔍 If ReSearchStalled = true, triggers Arr search before removal
3. ❌ Marks torrent as failed in qBittorrent
4. 🚫 Blacklists release in Arr instance
5. 🗑️ Removes torrent and files
6. 📢 Notifies Arr instance of failure
7. 🔄 Arr searches for new release (if ReSearch = true)

Slow Torrent Handling¶

What is a Slow Torrent?¶

A torrent is considered "slow" when:

• Download speed is very low (< 100 KB/s)
• Predicted ETA exceeds MaximumETA
• Progress is minimal over time

Configuration¶

[Radarr-Movies.Torrent]
# Ignore slow torrents (don't remove them)
DoNotRemoveSlow = true

# Maximum allowed ETA before considering failed (seconds)
MaximumETA = 604800  # 7 days

MaximumETA Calculation¶

qBitrr calculates ETA based on:

ETA = (Total Size - Downloaded Size) / Current Download Speed

Example:

• File size: 10 GB
• Downloaded: 2 GB
• Speed: 100 KB/s
• ETA: (8 GB) / (100 KB/s) = 23 hours

If MaximumETA = 18000 (5 hours), this torrent would be marked as failed.

Recommended MaximumETA Values¶

Formula: MaximumETA = Expected Download Time × 2 (safety margin)

Quick Reference:

Completion Percentage Protection¶

Maximum Deletable Percentage¶

Protects near-complete downloads from accidental removal:

[Radarr-Movies.Torrent]
# Don't delete torrents above this percentage
MaximumDeletablePercentage = 0.99  # 99%

How it works:

• Torrent at 98% complete → Can be removed if stalled
• Torrent at 99.5% complete → Protected from removal
• Allows failed imports to be retried

Values:

• 0.99 - (Default) Protect torrents above 99%
• 0.95 - Protect torrents above 95%
• 1.0 - Protect 100% complete only
• 0.0 - No protection (not recommended)

Torrent Age Filtering¶

Ignore Young Torrents¶

Prevents processing torrents that were just added:

[Radarr-Movies.Torrent]
# Ignore torrents younger than this (seconds)
IgnoreTorrentsYoungerThan = 180  # 3 minutes

Why?

• Torrents need time to connect to peers
• Metadata may not be fully loaded
• Prevents false "stalled" detection
• Gives qBittorrent time to start downloading

Recommended values:

• 180 - (Default) 3 minutes
• 120 - 2 minutes (aggressive)
• 300 - 5 minutes (conservative)

Tracker Health Monitoring¶

Dead Tracker Detection¶

qBitrr monitors tracker announce status:

[Radarr-Movies.Torrent.SeedingMode]
# Automatically remove dead trackers
RemoveDeadTrackers = false

# Remove trackers with these error messages
RemoveTrackerWithMessage = [
  "skipping tracker announce (unreachable)",
  "No such host is known",
  "unsupported URL protocol",
  "info hash is not authorized with this tracker"
]

When enabled:

• ✅ Detects tracker errors
• ✅ Removes non-responsive trackers
• ✅ Keeps working trackers
• ✅ Improves peer discovery

File Validation (FFprobe)¶

Automatic Media Verification¶

qBitrr uses FFprobe to validate downloaded media files:

[Settings]
# Auto-download and update FFprobe binary
FFprobeAutoUpdate = true

What FFprobe checks:

• ✅ File is playable
• ✅ Codec is valid
• ✅ Duration matches expected
• ✅ No corruption detected
• ✅ Audio tracks present

Validation workflow:

1. 📥 Torrent completes download
2. 🔍 qBitrr scans media files
3. 🎬 FFprobe validates each file
4. ✅ If valid → Trigger import
5. ❌ If invalid → Mark as failed, blacklist, re-search

FFprobe Binary Management¶

Automatic (recommended):

FFprobeAutoUpdate = true

• qBitrr downloads FFprobe from https://ffbinaries.com/downloads
• Automatically updates to latest version
• Stored in /config/qBitManager/ffprobe (native) or /config/qBitManager/ffprobe (Docker)

Manual:

FFprobeAutoUpdate = false

• Place your own FFprobe binary at /config/qBitManager/ffprobe.exe (Windows) or /config/qBitManager/ffprobe (Linux/macOS)
• qBitrr will use your provided binary

Disable validation:

• Remove FFprobe binary from /config/qBitManager/
• qBitrr will skip validation (not recommended)

Monitoring via WebUI¶

Real-Time Status¶

The qBitrr WebUI provides real-time health monitoring:

Processes Tab:

• View active torrent processing
• See health check results
• Monitor ETA calculations
• Track stalled torrent detection

Arr Tabs (Radarr/Sonarr/Lidarr):

• List all managed torrents
• Color-coded status indicators
• Progress bars
• ETA display
• Download speed

Status Colors:

• 🟢 Green - Downloading normally
• 🟡 Yellow - Slow download
• 🟠 Orange - Warning (approaching limits)
• 🔴 Red - Failed or stalled

Health Monitoring Best Practices¶

Tuning for Your Setup¶

For fast internet connections:

[Radarr-Movies.Torrent]
IgnoreTorrentsYoungerThan = 120  # 2 minutes
StalledDelay = 10  # 10 minutes
MaximumETA = 43200  # 12 hours
DoNotRemoveSlow = false  # Remove slow torrents

For slow/shared connections:

[Radarr-Movies.Torrent]
IgnoreTorrentsYoungerThan = 300  # 5 minutes
StalledDelay = 30  # 30 minutes
MaximumETA = 172800  # 48 hours
DoNotRemoveSlow = true  # Keep slow torrents

For private trackers:

[Radarr-Movies.Torrent]
IgnoreTorrentsYoungerThan = 300  # 5 minutes
StalledDelay = 45  # 45 minutes
MaximumETA = 259200  # 72 hours
DoNotRemoveSlow = true  # Very conservative
MaximumDeletablePercentage = 0.99  # Protect near-complete

Balancing Aggressiveness¶

%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#ff6b6b','primaryTextColor':'#000','primaryBorderColor':'#c92a2a','lineColor':'#868e96','secondaryColor':'#51cf66','tertiaryColor':'#4dabf7'}}}%%
graph LR
    subgraph Aggressive["⚡ Aggressive (Fast Replacement)"]
        direction TB
        A1["✅ Faster media availability"]
        A2["✅ Less time wasted on dead torrents"]
        A3["✅ Quick failure detection"]
        A4["❌ May remove salvageable downloads"]
        A5["❌ Higher indexer API usage"]
        A6["❌ More re-searches needed"]
    end

    subgraph Balanced["⚖️ Balanced (Default)"]
        direction TB
        B1["✅ Good availability speed"]
        B2["✅ Reasonable timeout periods"]
        B3["✅ Moderate API usage"]
        B4["✅ Works for most setups"]
        B5["⚠️ May need tuning"]
    end

    subgraph Conservative["🐢 Conservative (Patient Approach)"]
        direction TB
        C1["✅ Gives torrents more time"]
        C2["✅ Lower indexer API usage"]
        C3["✅ Fewer false positives"]
        C4["❌ Slower media availability"]
        C5["❌ May waste time on dead torrents"]
        C6["❌ Storage used longer"]
    end

    Aggressive -.->|tune based on results| Balanced
    Balanced -.->|tune based on results| Conservative

    style Aggressive fill:#ffe3e3,stroke:#c92a2a,stroke-width:2px
    style Balanced fill:#d3f9d8,stroke:#2f9e44,stroke-width:2px
    style Conservative fill:#e7f5ff,stroke:#1971c2,stroke-width:2px

Configuration Comparison:

Decision Guide:

1. Start with Balanced (default settings)
2. Monitor for 1 week - Check logs for premature removals
3. Adjust based on results:
4. Too many good torrents removed → Move toward Conservative
5. Too many dead torrents sitting → Move toward Aggressive
6. Fine-tune individual settings as needed

Troubleshooting Health Monitoring¶

Torrents Removed Too Quickly¶

Symptoms: Good torrents are being marked as failed

Solutions:

1. Increase stalled delay:

   StalledDelay = 30  # Up from 15
   

2. Increase ETA tolerance:

   MaximumETA = 172800  # Up from 86400
   

3. Enable slow torrent protection:

   DoNotRemoveSlow = true
   

4. Increase young torrent threshold:

   IgnoreTorrentsYoungerThan = 300  # Up from 180
   

Torrents Never Removed¶

Symptoms: Dead torrents sit forever, never cleaned up

Solutions:

1. Decrease stalled delay:

   StalledDelay = 10  # Down from 15
   

2. Set maximum ETA:

   MaximumETA = 86400  # 24 hours (was -1 disabled)
   

3. Disable slow torrent protection:

   DoNotRemoveSlow = false
   

4. Check logs for detection:

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

FFprobe Validation Failures¶

Symptoms: Valid files marked as corrupted

Solutions:

1. Check FFprobe binary:

   # Native
   ls -l ~/config/qBitManager/ffprobe
   
   # Docker
   docker exec qbitrr ls -l /config/qBitManager/ffprobe
   

2. Test FFprobe manually:

   ffprobe /path/to/media/file.mkv
   

3. Update FFprobe:

   FFprobeAutoUpdate = true
   

   Restart qBitrr to download latest version

4. Review validation logs:

   grep -i ffprobe ~/logs/Main.log
   

Related Documentation¶

• qBittorrent Configuration
• Torrent Settings
• Seeding Configuration
• Troubleshooting Common Issues