tommythebeast/arrstalledhandler repository overview

⁠ArrStalledHandler

ArrStalledHandler is a Python-based script designed to handle stalled downloads in Radarr⁠, Sonarr⁠, Lidarr⁠ and Readarr⁠ by taking actions such as removing, blocklisting, or blocklisting and re-searching for the affected items. It supports configuration through a .env file, logging for visibility, and is deployable via Docker for ease of use.

This repository is licensed under the GNU General Public License v3.0 (GPLv3)⁠.

Created by Tommy Vange Rød⁠. You can see the full list of credits here⁠.

This project is available on GitHub⁠, Docker Hub⁠ and the Unraid Community App store⁠.

⁠Features

• Automatic Handling of Stalled Downloads:
  • Detect stalled downloads based on error messages from Radarr/Sonarr/Lidarr/Readarr queues.
  • Detect download stuck on "Downloading Metadata" in qBittorrent and treat them as stalled.
  • Perform configurable actions such as:
    • Remove the stalled download.
    • Blocklist the stalled download.
    • Blocklist and re-trigger a search for the movie or episodes.
• Database Tracking:
  • Tracks stalled downloads in a SQLite database to ensure actions are only taken after a specified timeout period.
• Logging:
  • Verbose and informative logging controlled via configuration.
• Docker Support:
  • Easily deployable with Docker and customizable run intervals.

⁠Configuration

The script is fully configurable using environment variables specified in a .env file. Below is a description of each configuration option:

⁠.env Variables

To disable Radarr or Sonarr; leave the URL empty in the environment. If the service does not have a URL, then it is skipped. Multple services are allowed by using comma seperated values.

⁠How It Works

⁠Script Workflow

1. Initialization:

   • The script initializes a SQLite database (stalled_downloads.db) to track stalled downloads.
   • It fetches the current queue from Radarr and Sonarr APIs.

2. Detect Stalled Downloads:

   • The script identifies stalled downloads based on the error message: "The download is stalled with no connections".
   • [Optional] The script treats downloads with the error message "qBittorrent is downloading metadata" as stalled.

3. Timeout Check:

   • Downloads are only handled if they have been stalled longer than the configured STALLED_TIMEOUT.

4. Perform Configured Action:

   • Based on the STALLED_ACTION setting:
     • REMOVE: Removes the stalled download.
     • BLOCKLIST: Removes and blocklists the stalled download.
     • BLOCKLIST_AND_SEARCH: Removes, blocklists, and re-triggers a search for the movie or episodes.

5. Logging:

   • Logs detailed information about each action for visibility.

6. Repeat:

   • When running in Docker, the script waits for the RUN_INTERVAL duration and repeats the process.

⁠Deployment

⁠Unraid Deployment

1. Install the Community Apps extension as documented in this guide⁠.
2. Go to the Apps-section in your Unraid web-ui.
3. Search for ArrStalledHandler.
4. Click Install on the application.
5. Fill out the variables according to the Configuration⁠.
6. Click Apply.

Now the container should automatically start up and start handling your stalled downloads.

⁠Docker Deployment (Docker Hub⁠)

Docker compose

More info at Docker Docs⁠.

services:
  arr-stalled-handler:
    image: tommythebeast/arrstalledhandler:latest
    container_name: ArrStalledHandler
    restart: unless-stopped
    environment:
      RADARR_URL: "http://localhost:7878,http://otherhost:7878"
      RADARR_API_KEY: "your_radarr_api_key,your_2nd_radarr_api_key"
      SONARR_URL: "http://localhost:8989,http://otherhost:8989"
      SONARR_API_KEY: "your_sonarr_api_key,your_2nd_sonarr_api_key"
      LIDARR_URL: "http://localhost:8686,http://otherhost:8686"
      LIDARR_API_KEY: "your_lidarr_api_key,your_2nd_lidarr_api_key"
      READARR_URL: "http://localhost:8787,http://otherhost:8787"
      READARR_API_KEY: "your_readarr_api_key,our_2nd_readarr_api_key"
      STALLED_TIMEOUT: "3600"
      STALLED_ACTION: "BLOCKLIST_AND_SEARCH"
      VERBOSE: "false"
      RUN_INTERVAL: "300"
      COUNT_DOWNLOADING_METADATA_AS_STALLED: "false"

Docker CLI

More info at Docker Docs⁠.

Multi-line:

docker run -d \
  --name=ArrStalledHandler \
  -e RADARR_URL=http://localhost:7878,http://otherhost:7878 \
  -e RADARR_API_KEY=your_radarr_api_key,your_2nd_radarr_api_key \
  -e SONARR_URL=http://localhost:8989,http://otherhost:8989 \
  -e SONARR_API_KEY=your_sonarr_api_key,your_2nd_sonarr_api_key \
  -e LIDARR_URL=http://localhost:8686,http://otherhost:8686 \
  -e LIDARR_API_KEY=your_lidarr_api_key,your_2nd_lidarr_api_key \
  -e READARR_URL=http://localhost:8787,http://otherhost:8787 \
  -e READARR_API_KEY=your_readarr_api_key,our_2nd_readarr_api_key \
  -e STALLED_TIMEOUT=3600 \
  -e STALLED_ACTION=BLOCKLIST_AND_SEARCH \
  -e VERBOSE=false \
  -e RUN_INTERVAL=300 \
  -e COUNT_DOWNLOADING_METADATA_AS_STALLED=false \
  --restart unless-stopped \
  tommythebeast/arrstalledhandler:latest

One line:

docker run -d --name=ArrStalledHandler -e RADARR_URL=http://localhost:7878,http://otherhost:7878 -e RADARR_API_KEY=your_radarr_api_key,your_2nd_radarr_api_key -e SONARR_URL=http://localhost:8989,http://otherhost:8989 -e SONARR_API_KEY=your_sonarr_api_key,your_2nd_sonarr_api_key -e LIDARR_URL=http://localhost:8686,http://otherhost:8686  -e LIDARR_API_KEY=your_lidarr_api_key,your_2nd_lidarr_api_key -e READARR_URL=http://localhost:8787,http://otherhost:8787 -e READARR_API_KEY=your_readarr_api_key,our_2nd_readarr_api_key -e STALLED_TIMEOUT=3600 -e STALLED_ACTION=BLOCKLIST_AND_SEARCH -e VERBOSE=false -e RUN_INTERVAL=300 -e COUNT_DOWNLOADING_METADATA_AS_STALLED=false --restart unless-stopped tommythebeast/arrstalledhandler:latest

⁠Docker Deployment (Manual)

1. Clone the Repository:

   git clone https://github.com/your-username/ArrStalledHandler.git
   cd ArrStalledHandler
   

   Copy

2. Configure Environment:

   Create a .env file and populate it with the required variables:

   RADARR_URL=http://localhost:7878,http://otherhost:7878
   RADARR_API_KEY=aaaabbbbcccc111122223333,xxxxyyyyzzzz777788889999
   SONARR_URL=http://localhost:8989,http://otherhost:8989
   SONARR_API_KEY=aaaabbbbcccc111122223333,xxxxyyyyzzzz777788889999
   LIDARR_URL=http://localhost:8686,http://otherhost:8686
   LIDARR_API_KEY=aaaabbbbcccc111122223333,xxxxyyyyzzzz777788889999
   READARR_URL=http://localhost:8787,http://otherhost:8787
   READARR_API_KEY=aaaabbbbcccc111122223333,xxxxyyyyzzzz777788889999
   STALLED_TIMEOUT=3600
   STALLED_ACTION=BLOCKLIST_AND_SEARCH
   VERBOSE=false
   RUN_INTERVAL=300
   COUNT_DOWNLOADING_METADATA_AS_STALLED=false
   

   Copy

3. Build the Docker Image:

   docker-compose build .
   

   Copy

4. Run the Docker Container:

   docker-compose up -d
   

   Copy

⁠Local Installation

Requires Python 3.13

1. Clone the Repository:

   git clone https://github.com/your-username/ArrStalledHandler.git
   cd ArrStalledHandler
   

   Copy

2. Install Dependencies:

   pip install -r requirements.txt
   

   Copy

3. Configure Environment:

   Create a .env file and populate it with the required variables:

   RADARR_URL=http://localhost:7878,http://otherhost:7878
   RADARR_API_KEY=aaaabbbbcccc111122223333,xxxxyyyyzzzz777788889999
   SONARR_URL=http://localhost:8989,http://otherhost:8989
   SONARR_API_KEY=aaaabbbbcccc111122223333,xxxxyyyyzzzz777788889999
   LIDARR_URL=http://localhost:8686,http://otherhost:8686
   LIDARR_API_KEY=aaaabbbbcccc111122223333,xxxxyyyyzzzz777788889999
   READARR_URL=http://localhost:8787,http://otherhost:8787
   READARR_API_KEY=aaaabbbbcccc111122223333,xxxxyyyyzzzz777788889999
   STALLED_TIMEOUT=3600
   STALLED_ACTION=BLOCKLIST_AND_SEARCH
   VERBOSE=false
   RUN_INTERVAL=300
   COUNT_DOWNLOADING_METADATA_AS_STALLED=false
   

   Copy

4. Run the Script:

   python main.py
   

   Copy

⁠Logging

• Logs are written to the console and are controlled by the VERBOSE environment variable.
• If VERBOSE is set to true, debug-level logs are enabled.

Example log output:

INFO: Checking stalled downloads in Radarr...
INFO: Handling Download ID 1462067687 in Radarr (elapsed time: 400 seconds).
INFO: Triggering search for Movie ID 770 in Radarr using Command API...
INFO: Script execution completed. Sleeping for 300 seconds...

⁠Troubleshooting

1. Script Not Executing Actions:
   • Check if STALLED_TIMEOUT is too high.
   • Verify the stalled downloads are correctly detected via Radarr/Sonarr queues.

⁠Credits

⁠Author

Tommy Vange Rød ⁠

You can find more of my work on my GitHub profile⁠ or connect with me on LinkedIn⁠.

⁠Contributors

Huge thanks to everyone who dedicates their valuable time to improving, perfecting, and supporting this project!

supernovatroubling ⁠

⁠GNU General Public License v3.0 (GPLv3)

The GNU General Public License v3.0 (GPLv3) is a free, copyleft license for software and other creative works. It ensures your freedom to share, modify, and distribute all versions of a program, keeping it free software for everyone.

Full license can be read here⁠ or at gnu.org⁠.

⁠Key Points:

1. Freedom to Share and Change:

   • You can distribute copies of GPLv3-licensed software.
   • Access the source code.
   • Modify the software.
   • Create new free programs using parts of it.

2. Responsibilities:

   • If you distribute GPLv3 software, pass on the same freedoms to recipients.
   • Provide the source code.
   • Make recipients aware of their rights.

3. No Warranty:

   • No warranty for this free software.
   • Developers protect your rights through copyright and this license.

4. Marking Modifications:

   • Clearly mark modified versions to avoid attributing problems to previous authors.