plungarr

Unclogs your Sonarr/Radarr download pipeline. plungarr watches the queues and your SABnzbd downloads, and automatically fixes the stuck states that otherwise sit there until a human notices: dead usenet posts downloading at 0 B/s forever, completed downloads wedged on "manual import required", junk releases that can never import. It also reports suspicious library files for manual inspection. What it can't fix safely, it reports and leaves alone.

Single-file Node 22 service, no dependencies. Talks to everything over the apps' own HTTP APIs. Any number of Sonarr and Radarr instances can be configured in one container, which matters if they share a SABnzbd: the stall watcher only treats a download as an orphan when no configured instance owns it.

What it does

Sonarr / Radarr — queue handling (every cycle, default 5 min)

The four *_ACTION settings take one of three values:

Items in these classes always wait one cycle before plungarr acts, even when the arr reports them as import-blocked, so a client that is still extracting after "completed" is never raced.

Sonarr / Radarr — periodic reviews

SABnzbd — stall watcher (every cycle, optional)

Enabled by setting SABNZBD_URL + SABNZBD_API_KEY.

Notifications (optional)

Off unless NOTIFY_URL is set; without it everything still goes to the container log. With it, plungarr POSTs digests to one receiver:

Each category has its own cadence: immediate (batched per cycle, sent at the end of it), daily, weekly, monthly, or none.

Digests fire at NOTIFY_DIGEST_HOUR (default 8, container local time), on NOTIFY_DIGEST_DAY (default monday) for weekly and NOTIFY_DIGEST_DAY_OF_MONTH (default 1) for monthly. Categories sharing a slot are merged into one message. An attention item is sent once when first seen and again only after NOTIFY_REMIND_DAYS (default 7; 0 disables reminders). Pending items and sent-times live in the state file, so restarts neither drop nor duplicate a digest. A startup message is sent once so a bad URL or token shows up immediately. Delivery failures are logged and retried next cycle; they never block queue processing. Dry run logs the digest text and never POSTs.

Quick start

Requires Docker with Compose, plus API keys from Sonarr and/or Radarr (Settings → General → Security). SABnzbd URL + API key are optional and enable the stalled/dead-download watcher.

git clone https://github.com/stove-bison/plungarr.git && cd plungarr
cp .env.example .env    # fill in your URLs and API keys
docker compose up -d --build

Watch it work:

docker logs -f plungarr

One line per action, plus a heartbeat every cycle (fictional examples):

2026-01-01T12:00:00Z | sonarr | IMPORTED | Example.Show.S01E02.720p.WEB.h264-GROUP | 1 file(s) sent to ManualImport
2026-01-01T12:00:01Z | sonarr | REMOVED+REPLACE | Example.Series.S02.720p.WEB-DL | dead_empty
2026-01-01T12:00:02Z | sonarr | PROBLEM | Example Show S01E07 "Example Episode" | 3 failed grab(s) in 48h, none imported since
2026-01-01T12:00:03Z | cycle  | HEARTBEAT | queues processed in 3s | 2 gated, sweep idle

Grep for PROBLEM to see what needs your attention; everything else is handled.

Unraid

A Docker template is included: in the Docker tab choose Add Container, set the template URL to https://raw.githubusercontent.com/stove-bison/plungarr/master/templates/plungarr.xml, fill in your URLs and API keys, done. The image is published to ghcr.io/stove-bison/plungarr:latest after tests pass on pushes to master.

The container runs as uid 1000; if the appdata folder mapped to /state isn't writable by it, plungarr still runs fine — it just keeps its first-seen/loop-guard state in memory and starts fresh on restart (a state save failed log line tells you this is happening). Stall timers always start fresh after a restart.

Configuration

Everything is an environment variable with a sane default — see .env.example for the full annotated list. The essentials:

Safety rails

• Import-blocked items are acted on immediately (the arr has already given up on them); anything transitional must be seen stuck across two cycles first, so an active import is never raced.
• Blocklist loop guard: indexers re-serve the same junk under new GUIDs; after 2 blocklists of the same release title, plungarr stops searching for a replacement.
• Corruption review is always report-only. Missing metadata, unknown age, and unusual bitrate can never authorize deleting a library file.
• Stall timers reset on pause, head changes, restart, failed queue reads, and gaps longer than two configured cycle intervals (with a minimum of 60 seconds).
• Checking, fetching repair data, verifying, repairing, queued, and propagating jobs are excluded from automatic missing-article removals.
• Ownership checks read all arr queue pages. Failed, incomplete, or inconsistent snapshots stop the removal; SAB queue observation is also paginated.
• Invalid numeric or boolean configuration stops startup with the setting name.
• Per-item action dedupe (30 min) while the arr catches up.
• DRY_RUN=true to watch what it would do first.

The older CORRUPT_MAX_DELETES, CORRUPT_LOOP_LIMIT, CORRUPT_MIN_AGE_HOURS, and CORRUPT_NO_SEARCH_SERIES_IDS settings no longer control actions: library deletion has been removed. Old numeric values are still validated so malformed configuration does not pass silently.

Development checks

Run node --check janitor.mjs and node --test with Node 22. Tests use synthetic data, mocked APIs, and a local HTTP fixture; they do not contact configured media services. Pull requests and branch pushes run the tests before an eligible image publication can proceed.

License

MIT