# Arr apps

Radarr and Sonarr credentials and automatic stuck-queue handling. Config key:
`arr.instances` (`NZBDAV_CONFIG__ARR__INSTANCES`; see
[headless](https://www.infinidysk.com/v1/configuration/headless/)).

| Setting | What it does |
|---|---|
| Name | Optional display name; Overview Arr Health falls back to the host URL. |
| Enabled | When off, the instance is excluded from queue management, Arr-linked repairs **and** Arr Health. Default on. |
| Host / API Key | One pair per Radarr or Sonarr instance. **Test Conn** appears once both are filled. |
| Show Arr Health on Overview<br/>`arr.health-enabled` | Polls enabled instances for the Overview widget (`NZBDAV_CONFIG__ARR__HEALTH_ENABLED`). Default on. |
| Automatic replacement searches / Per window (minutes) | Replacement-search limit per movie or episode (1–10 searches, 1–1440 minutes). Default 3 in 30 minutes. |
| Automatic queue management | Per status message: **Do Nothing**, **Remove**, **Remove and Blocklist**, or **Remove, Blocklist, and Search**. Default **Do Nothing**. |

**Test Conn** validates host reachability, API key auth, and a successful API response
(`GET /api`). It works with already-saved (masked) API keys — you do not need to re-enter
the key after reload. Failures show a reason (authentication, HTTP status, or network error).

Only **Usenet** queue items that Radarr or Sonarr reports as completed or awaiting import
are acted upon. Downloads that are still queued or downloading are never removed by these
rules. Typical mappings:

- **Remove, Blocklist, and Search** — no eligible files, samples, no audio tracks
- **Remove and Blocklist** — not an upgrade / custom format
- **Remove** — already imported
- **Do Nothing** — ID mismatches and similar manual-import cases

Any action other than **Do Nothing** tells the Arr to delete the queue record with `removeFromClient=true`. The Arr then removes the download from infinidysk History even when its own **Remove Completed** checkbox is off. That is independent of mounted files, which stay.

## Docker hostnames and proxies {#docker-hostnames-and-proxies}

Radarr, Sonarr, and [Prowlarr](https://www.infinidysk.com/v1/configuration/indexers/#prowlarr-pull-sync) hosts whose hostname
has **no dot** — Docker Compose service names such as `http://sonarr:8989` — are always
contacted **directly**, even when the container has `HTTP_PROXY` / `HTTPS_PROXY` set.
Names like that only resolve on the local container network, so sending them through a
proxy produced connection failures that disappeared when the host was changed to an IP
address. Dotted hostnames and IP literals keep the normal proxy policy, including
`NO_PROXY`. This applies only to infinidysk's own Arr and Prowlarr management calls;
imported indexer traffic still follows the per-indexer proxy settings.

Connections to Arr and Prowlarr hosts are recycled after two minutes so a stale
DNS answer or a recreated container cannot pin a dead connection.

Request budgets are unchanged: Arr health polls allow 10 seconds per call, other Radarr/Sonarr
requests 30 seconds, and Prowlarr requests 15 seconds. When one expires, logs, Test Conn, and
the Overview Arr Health panel report it as a timeout with the routing used, for example:

```text
Arr health poll failed for "http://sonarr:8989". Reason: "Sonarr queue
request to http://sonarr:8989 timed out after 10 seconds; routing: direct
(single-label hostname)."
```

"Operation canceled" is no longer used for expired waits; it now indicates only a genuine
shutdown or caller cancellation.

## Releases stuck in Awaiting import

Sometimes Sonarr completes a download but refuses to import it because the
season numbering in the release name disagrees with Sonarr's metadata. A
representative queue reason is:

> Episode 11x01 was unexpected considering the
> `<release-name>` folder name

Sonarr determines episode identity and import eligibility. infinidysk cannot
remap the episode or force Sonarr to import it, but it can automatically
resolve the stuck queue record.

In **Settings → Arr Apps → Automatic queue management**, choose an action
for **Episode(s) was/were unexpected considering the folder name**:

- **Remove** removes the stuck queue record.
- **Remove and Blocklist** also prevents Sonarr from accepting that release
  again.
- **Remove, Blocklist, and Search** also asks Sonarr to find a replacement.

All queue rules default to **Do Nothing**. With that default, the item remains
in Awaiting Import until an operator resolves it. The Overview Arr Health
panel reports unusually long waits but does not mutate the queue.

Use **Remove, Blocklist, and Search** when an automatic replacement is wanted.
A numbering disagreement can affect every indexed release for the episode;
the per-media replacement-search limit eventually withholds additional
searches while continuing to remove and blocklist rejected releases.

## Replacement-search safety limit <a class="since" href="https://github.com/infinidysk/infinidysk/releases/tag/v1.2.4">since 1.2.4</a>

**Remove, Blocklist, and Search** is bounded to **3 automatic replacement searches in
30 minutes per Radarr movie or Sonarr episode** by default. Once a media item reaches
that limit, infinidysk still removes and blocklists its rejected release but does not
start another automatic search. Adjust both values in **Automatic queue management**
when a library needs a stricter or more permissive policy. The same per-media cap also
bounds replacement searches triggered by health-check repairs, which additionally keep
their own per-library-file rate limit.

The queue-monitor warning includes the matching Arr import message, so support packs
show the actual rejection (for example, an archive, an ineligible file, or an import
path problem) that led to the action.

Disabling an instance opts it out of stuck-queue actions, Arr-linked repairs, and health polling. Turn **Show Arr Health on Overview** off when you still want queue rules without Overview polling.

## Blocklisted re-grab protection <a class="since" href="https://github.com/infinidysk/infinidysk/releases/tag/v1.4.0">since 1.4.0</a>

When a queue rule applies **Remove and Blocklist** or **Remove, Blocklist, and Search**,
infinidysk remembers a bounded sample of article IDs from the removed download. A later NZB
containing any remembered article is failed in the download queue before import or Usenet article
requests, even when another indexer supplied it under a different release name. Plain **Remove**
does not mark an upload as rejected.

This memory is process-local and bounded. Evidence capture is also limited to two seconds per
monitoring pass so queue actions are not delayed by local evidence collection. It is lost on
restart, entries can be evicted, and
provider configuration changes can clear it. Protection also requires the completed download's
local history and stored NZB to still exist. A replacement that starts importing before Arr's
delete request returns can pass the check; later re-grabs are protected after Arr confirms the
blocklist action succeeded.

## Arr Health on the Overview dashboard <a class="since" href="https://github.com/infinidysk/infinidysk/releases/tag/v1.2.0">since 1.2.0</a>

When at least one Radarr or Sonarr instance is configured **and enabled**, Overview shows a compact **Arr Health** section: instance reachability, imports in the selected dashboard window, median/P95 handoff latency (infinidysk download completed → Arr `DownloadFolderImported`), queue depth, and items waiting unusually long for import.

## Awaiting detail <a class="since" href="https://github.com/infinidysk/infinidysk/releases/tag/v1.2.5">since 1.2.5</a>

**Queue** is every item Arr currently tracks. **Awaiting** is the completed or
`importPending`/`importing` subset, so the two counts intentionally differ.
The widget reports the true Awaiting total while showing only its longest waits;
each displayed row includes the Arr status reason when one is available. Related
season-pack rows with the same download are grouped in the detail list.

The feature is **completely dormant** otherwise:

- No Overview widget
- No background polling or Arr HTTP
- No metrics writes or Arr Health log lines

Turn off **Show Arr Health on Overview** (`arr.health-enabled`) to keep instances for queue rules/repairs without health polling.

Handoff events are stored in the local metrics database (`metrics.sqlite`) for **90 days**, so the Overview **All** window for this widget is effectively about 90 days. API keys are never sent to the widget.

Back up `/config` before upgrading: the metrics store gains an additive `ArrImportEvents` table that auto-applies on startup.

Headless `NZBDAV_CONFIG__ARR__INSTANCES` JSON that includes the new `Name` / `Enabled` properties **cannot roll back** to an older image (structured ENV config is not forward compatible — see [headless](https://www.infinidysk.com/v1/configuration/headless/)).

[Connect Arr](https://www.infinidysk.com/v1/getting-started/connect-arr/)