Release of v2.2.0: Sportarr, qBit API_Key, bug fixes

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,152 @@
+name: 🐛 Bug Report
+description: Report a reproducible problem with decluttarr
+title: "[Bug] "
+labels: ["Bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug. **Please fill in every required field** — incomplete reports take much longer to resolve and may be closed pending more info.
+
+        Before submitting, please confirm:
+        - You've read the ReadMe, especially the **Dependencies & Hints & FAQ** section. 
+          Make sure you read the correct ReadMe version:
+
+          - [**LATEST** ReadMe](https://github.com/ManiMatter/decluttarr/blob/latest/README.md) if you use ```latest``` code
+          - [**DEV** ReadMe](https://github.com/ManiMatter/decluttarr/blob/dev/README.md) if you use ```dev``` code
+        - You've searched [open and closed issues](https://github.com/ManiMatter/decluttarr/issues?q=is%3Aissue) for the same problem
+        - This is a reproducible bug, not a configuration question (use [Discussions](https://github.com/ManiMatter/decluttarr/discussions) for those)
+
+  - type: input
+    id: version
+    attributes:
+      label: Decluttarr commit hash
+      description: |
+        The **short commit hash** of the build you're running. `latest` / `dev` tags move too quickly to be useful for reproduction, so please give us the specific commit.
+
+        - **Docker users:** grab it from the `short_commit_id` line in the `🛠️  Decluttarr - Settings 🛠️` startup banner (you'll be pasting the full banner in the logs field below)
+        - **Local Python users:** run `git rev-parse --short HEAD`
+      placeholder: "e.g. 51b6a4c"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: deployment
+    attributes:
+      label: Deployment method
+      options:
+        - Docker Compose with config.yaml
+        - Docker Compose with environment variables
+        - docker run
+        - Local Python (main.py)
+        - Other (describe under "Steps to reproduce")
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Host OS / architecture
+      description: |
+        Where decluttarr is running. Path-related bugs (especially `detect_deletions`) and qBit cookie issues sometimes behave differently on Windows or ARM.
+      options:
+        - Linux x86_64 (amd64)
+        - Linux ARM (arm64 / armv7)
+        - macOS
+        - Windows
+        - Other (describe under "Steps to reproduce")
+    validations:
+      required: true
+
+  - type: input
+    id: arr_versions
+    attributes:
+      label: "*arr instance versions"
+      description: Versions of any Sonarr / Radarr / Lidarr / Readarr / Whisparr instances involved in the bug.
+      placeholder: "e.g. Sonarr 4.0.10, Radarr 5.18.4"
+    validations:
+      required: true
+
+  - type: input
+    id: download_client_version
+    attributes:
+      label: Download client + version
+      description: qBittorrent / SABnzbd / etc. and version. Write `n/a` if the bug doesn't involve a download client.
+      placeholder: "e.g. qBittorrent 5.2.0, or n/a"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: test_run
+    attributes:
+      label: test_run state
+      description: |
+        Removal-related bugs behave very differently with `test_run: true` (no actual removals) vs `false`. Pick the value of `general.test_run` (or `TEST_RUN`) when the bug occurred.
+      options:
+        - "false (production — actual removals)"
+        - "true (test_run mode — no actual removals)"
+        - Reproduces with both
+        - N/A (bug doesn't involve removal logic)
+    validations:
+      required: true
+
+  - type: dropdown
+    id: frequency
+    attributes:
+      label: Reproduction frequency
+      options:
+        - Always (every cycle / every time)
+        - Sometimes (intermittent)
+        - Once / haven't tried again
+        - Unknown
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Decluttarr startup banner + debug logs
+      description: |
+        Please follow these three steps to produce a useful log dump:
+
+        1. **Disable jobs not related to your issue** in your config — keeps the logs focused and short
+        2. **Set `log_level: DEBUG`** (or `VERBOSE` if DEBUG is too noisy)
+        3. **Restart decluttarr and paste everything from the `🛠️  Decluttarr - Settings 🛠️` startup banner through the cycle that exhibits the bug**
+
+        The startup banner already contains `image_tag` / `short_commit_id` and the entire active config (general, jobs, instances, download clients) with API keys masked as `*****`.
+
+        **Still sanitize before pasting:** scrub any `?apikey=...` query parameters, `Authorization:` headers, session cookies, and any arr/qBit URLs you'd rather not share. Decluttarr already redacts `X-Api-Key` headers but not query-string keys.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Start decluttarr with the config above
+        2. ...
+        3. ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Anything else?
+      description: Screenshots, related issues, what you've already tried, hardware/OS details if relevant, etc.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,10 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 💬 Questions, usage help, config troubleshooting
+    url: https://github.com/ManiMatter/decluttarr/discussions
+    about: |
+      For general questions, configuration help, or "why is this happening" — please use Discussions instead of opening an issue. The issue tracker is reserved for reproducible bugs and feature requests.
+  - name: 📚 README & FAQ
+    url: https://github.com/ManiMatter/decluttarr#dependencies--hints--faq
+    about: |
+      Many common problems (qBit cookie issues, multi-instance YAML format, "no valid arr instances" errors, etc.) are covered in the README's Dependencies & Hints & FAQ section. Please check there first.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,41 @@
+name: ✨ Feature Request
+description: Suggest a new feature or enhancement
+title: "[Feature] "
+labels: ["Feature"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for proposing an improvement! Please make sure there isn't already an [open issue](https://github.com/ManiMatter/decluttarr/issues?q=is%3Aissue+is%3Aopen+label%3AFeature) or [discussion](https://github.com/ManiMatter/decluttarr/discussions) covering the same idea.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: Describe the use case or pain point that the feature would address. What are you trying to accomplish that's currently awkward, manual, or impossible?
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: |
+        How would this feature work from the user's perspective?
+        - What does the config look like?
+        - What does decluttarr do at runtime?
+        - Are there new env vars / yaml keys / log messages?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Workarounds you've tried, other tools that solve this differently, or alternative implementations you've thought through.
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Anything else?
+      description: Mockups, references, related issues, or willingness to contribute a PR.

.github/workflows/build.yml

@@ -57,6 +57,9 @@ jobs:
     needs: unit-tests
     runs-on: ubuntu-latest
     if: github.event_name == 'push'
+    permissions:
+      contents: read
+      packages: write
     steps:
       - uses: actions/checkout@v4
         with:

README.md

@@ -1,7 +1,14 @@
 _Like this app? Thanks for giving it a_ ⭐️
 
 # **Decluttarr**
-**Decluttar V2 was released on Nov 1st, 2025 with _breaking config file changes_.**
+_Couple of quick hints:_
+
+**1. Are you looking at the right ReadMe?**
+Check that the ReadMe version corresponds to the branch you are using (i.e. ```latest``` or ```dev```). Default view on this GitHub repo is ```dev``` branch, but you are most likely using ```latest``` (as per below [instructions](#getting-started)). Thus make sure you change the branch of the ReadMe if that‘s the case:
+- [**LATEST** ReadMe](https://github.com/ManiMatter/decluttarr/blob/latest/README.md)
+- [**DEV** ReadMe](https://github.com/ManiMatter/decluttarr/blob/dev/README.md)
+
+**2. Decluttar V2 was released on Nov 1st, 2025 with _breaking config file changes_.**
 
 Looking to **upgrade from V1 to V2**? Look [here](#upgrading-from-v1-to-v2)
 
@@ -20,6 +27,7 @@ Looking to **upgrade from V1 to V2**? Look [here](#upgrading-from-v1-to-v2)
     - [LOG_LEVEL](#log_level)
     - [TEST_RUN](#test_run)
     - [TIMER](#timer)
+    - [REQUEST_TIMEOUT](#request_timeout)
     - [SSL_VERIFICATION](#ssl_verification)
     - [IGNORE_DOWNLOAD_CLIENTS](#ignore_download_clients)
     - [PRIVATE_TRACKER_HANDLING / PUBLIC_TRACKER_HANDLING](#private_tracker_handling--public_tracker_handling)
@@ -49,14 +57,15 @@ Looking to **upgrade from V1 to V2**? Look [here](#upgrading-from-v1-to-v2)
     - [READARR](#readarr)
     - [LIDARR](#lidarr)
     - [WHISPARR](#whisparr)
+    - [SPORTARR](#sportarr)
   - [Downloaders](#download-clients)
     - [QBITTORRENT](#qbittorrent)
 
 ## Overview
 
 Decluttarr is a helper tool that works with the *arr-application suite, and automates the clean-up for their download queues, keeping them free of stalled / redundant downloads. 
 
-It supports [Radarr](https://github.com/Radarr/Radarr/), [Sonarr](https://github.com/Sonarr/Sonarr/), [Readarr](https://github.com/Readarr/Readarr/), [Lidarr](https://github.com/Lidarr/Lidarr/), and [Whisparr](https://github.com/Whisparr/Whisparr/).
+It supports [Radarr](https://github.com/Radarr/Radarr/), [Sonarr](https://github.com/Sonarr/Sonarr/), [Sportarr](https://github.com/Sportarr/Sportarr/), [Readarr](https://github.com/Readarr/Readarr/), [Lidarr](https://github.com/Lidarr/Lidarr/), and [Whisparr](https://github.com/Whisparr/Whisparr/).
 
 Feature overview:
 
@@ -193,6 +202,7 @@ services:
       LOG_LEVEL: INFO
       TEST_RUN: True
       TIMER: 10
+      # REQUEST_TIMEOUT: 15
       # IGNORED_DOWNLOAD_CLIENTS: >
       #   - emulerr
       # SSL_VERIFICATION: true
@@ -267,6 +277,10 @@ services:
         - base_url: "http://sonarr2:8989"
           api_key: "$SONARR_API_KEY"
 
+      # SPORTARR: >
+      #   - base_url: "http://sportarr:1867"
+      #     api_key: "$SPORTARR_API_KEY"
+
       # RADARR: >
       #   - base_url: "http://radarr:7878"
       #     api_key: "$RADARR_API_KEY"
@@ -286,8 +300,9 @@ services:
       # --- Download Clients ---
       QBITTORRENT: >
         - base_url: "http://qbittorrent:8080"
-          # username: "$QBIT_USERNAME" # (optional -> if not provided, assuming not needed)
-          # password: "$QBIT_PASSWORD" # (optional -> if not provided, assuming not needed)
+          # api_key: "$QBIT_API_KEY" # (recommended -> requires qBittorrent 5.2.0+; takes precedence over username/password)
+          # username: "$QBIT_USERNAME" # (legacy -> for qBittorrent < 5.2; ignored if api_key is set)
+          # password: "$QBIT_PASSWORD" # (legacy -> for qBittorrent < 5.2; ignored if api_key is set)
           name: "qBittorrent 1" # (optional -> if not provided, assuming "qBittorrent". Must correspond with what is specified in your *arr as download client name)
         - base_url: "http://qbittorrent:8080"
           name: "qBittorrent 2" 
@@ -399,6 +414,13 @@ Configures the general behavior of the application (across all features)
 -   Unit: Minutes
 -   Is Mandatory: No (Defaults to 10)
 
+#### REQUEST_TIMEOUT
+
+-   Timeout used for HTTP/API requests to *arr and download clients
+-   Type: Integer or Float
+-   Unit: Seconds
+-   Is Mandatory: No (Defaults to 15)
+
 #### SSL_VERIFICATION
 
 -   Turns SSL certificate verification on or off for all API calls
@@ -422,8 +444,9 @@ Configures the general behavior of the application (across all features)
     -   "remove" means that torrents are removed (default behavior)
     -   "skip" means they are disregarded (which some users might find handy to protect their private trackers prematurely, i.e., before their seed targets are met)
     -   "obsolete_tag" means that rather than being removed, the torrents are tagged. This allows other applications (such as [qbit_manage](https://github.com/StuffAnThings/qbit_manage) to monitor them and remove them once seed targets are fulfilled)
+    -   "remove_from_queue" behaves like "remove" on the *arr side (the queue entry is cleared, and blocklisted if the job blocklists), but leaves the torrent untouched in the download client. Use this when the torrent still carries a hit-and-run obligation you must honour: the *arr stops waiting on a download that will never import and is free to grab an alternative, while seeding continues and another application (such as [qbit_manage](https://github.com/StuffAnThings/qbit_manage)) retires the torrent on the tracker's terms. Unlike "obsolete_tag" this clears the queue entry immediately rather than waiting for the torrent to disappear
 -   Type: String
--   Permissible Values: remove, skip, obsolete_tag
+-   Permissible Values: remove, remove_from_queue, skip, obsolete_tag
 -   Is Mandatory: No (Defaults to remove)
 
 
@@ -551,11 +574,13 @@ This is the interesting section. It defines which job you want decluttarr to run
 -   Steers whether downloads stuck obtaining metadata are removed from the queue
 -   Blocklisted: Yes
 -   Type: Boolean or Dict
--   Permissible Values: True, False or max_strikes (int)
+-   Permissible Values: True, False or max_strikes (int), detect_via_missing_size (bool)
 -   Is Mandatory: No (Defaults to False)
 -   Note:
       - With max_strikes you can define how many times this torrent can be caught before being removed
       - Instead of configuring it here, you may also configure it as a default across all jobs or use the built-in defaults (see further above under "max_strikes")
+      - By default, this check relies on the "qBittorrent is downloading metadata" message that qBittorrent surfaces in the \*arr queue. Other download clients (e.g. Transmission, Deluge) do not surface such a message, so a torrent stuck fetching metadata stays undetected (see [#57](https://github.com/ManiMatter/decluttarr/issues/57)).
+      - Set `detect_via_missing_size: true` to additionally flag, regardless of download client, queued items whose size is not yet known (size 0), which is the client-agnostic signature of "no metadata yet". This is debounced by max_strikes. Defaults to False to keep existing (qBittorrent) behavior unchanged.
 
 #### REMOVE_MISSING_FILES
 
@@ -679,6 +704,8 @@ Defines arr-instances on which download queue should be decluttered
 - Equivalent of [Radarr](#radarr)
 #### Whisparr
 - Equivalent of [Radarr](#radarr)
+#### Sportarr
+- Equivalent of [Radarr](#radarr)
 
 
 ---
@@ -695,8 +722,9 @@ Supported download clients: **qBittorrent** and **SABnzbd**.
 -   Type: List of qbit instances
 -   Keys per instance
     - base_url: URL under which the qbit can be reached (mandatory)
-    - username: Optional - only needed if your qbit requires authentication (which you may not need if you have configured qbit in a way that it disables it for local connections)
-    - password: Optional - see above
+    - api_key: Recommended - qBittorrent API key (requires qBittorrent 5.2.0 or newer; generate it under Web UI settings). Authenticates without storing credentials, and takes precedence over username/password if both are set.
+    - username: Legacy - only for qBittorrent < 5.2, or if your qbit requires authentication (which you may not need if qbit disables it for local connections). Ignored when api_key is set.
+    - password: Legacy - see above
     - name: Optional. Needs to correspond with the name that you have set up in your Arr instance. Defaults to "qBittorrent"
 
 #### SABNZBD

config/config_example.yaml

@@ -2,10 +2,12 @@ general:
   log_level: INFO
   test_run: true
   timer: 10
+  # request_timeout: 15 # Optional: timeout for all HTTP/API calls in seconds
   # ignored_download_clients: ["emulerr"]
   # ssl_verification: false # Optional: Defaults to true
-  # private_tracker_handling: "obsolete_tag" # remove, skip, obsolete_tag. Optional. Default: remove
-  # public_tracker_handling: "remove"  # remove, skip, obsolete_tag. Optional. Default: remove
+  # request_timeout: 15 # Optional: Request timeout in seconds. Defaults to 15. Can be overridden per instance.
+  # private_tracker_handling: "obsolete_tag" # remove, remove_from_queue, skip, obsolete_tag. Optional. Default: remove
+  # public_tracker_handling: "remove"  # remove, remove_from_queue, skip, obsolete_tag. Optional. Default: remove
   # obsolete_tag: "Obsolete" # optional. Default: "Obsolete"
   # protected_tag: "Keep" # optional. Default: "Keep"
 
@@ -52,6 +54,10 @@ instances:
   sonarr:
     - base_url: "http://sonarr:8989"
       api_key: "xxxx"
+      # timeout: 30 # Optional: Overrides general timeout for this instance.
+  # sportarr:
+  #   - base_url: "http://sportarr:1867"
+  #     api_key: "xxxx"
   radarr:
     - base_url: "http://radarr:7878"
       api_key: "xxxx"
@@ -68,9 +74,11 @@ instances:
 download_clients:
   qbittorrent:
     - base_url: "http://qbittorrent:8080" # You can use decluttarr without qbit (not all features available, see readme).
-      # username: xxxx # (optional -> if not provided, assuming not needed)
-      # password: xxxx # (optional -> if not provided, assuming not needed)
+      # api_key: "qbt_xxxx" # (recommended -> requires qBittorrent 5.2.0+; generate under Web UI settings. Takes precedence over username/password.)
+      # username: xxxx # (legacy -> for qBittorrent < 5.2; ignored if api_key is set)
+      # password: xxxx # (legacy -> for qBittorrent < 5.2; ignored if api_key is set)
       # name: "qBittorrent" # (optional -> if not provided, assuming "qBittorrent". Must correspond with what is specified in your *arr as download client name)
+      # timeout: 30 # (optional -> overrides general timeout for this instance)
   # sabnzbd:
   #   - base_url: "http://sabnzbd:8080" # SABnzbd server URL
   #     api_key: "your_api_key_here" # (required -> SABnzbd API key)