Failure, Memory, and the Art of Trying Again

A failed download is not just an error to display and forget. In Sonarr, it can change what the system considers worth trying next. This chapter examines how Sonarr uses history, blocklists, queue state, quality policy, and conditional re-search to turn failure into bounded feedback. The reader should be able to distinguish a failed transfer from a failed import, a duplicate from a policy rejection, and a useful retry from blind repetition.

That distinction matters because the visible symptom is often the same: an episode is still missing. The cause may be that a client never accepted the release, that the release was accepted but its files could not be imported, that the candidate was already processed, or that the library's policy deliberately rejected it. Sonarr's memory exists to keep those causes from collapsing into one endless loop.

The history record is also a control input

Sonarr records more than the final presence or absence of a file. Its history includes grabs, imports, failures, deletes, renames, and ignored items, along with source titles, identifiers, quality, protocol, indexer, size, dates, and custom-format scores. A download-level history tracks whether an external item was grabbed, imported, failed, or ignored. Together, these records answer two different questions.

The first is audit: what happened to this episode or download? The second is control: what should Sonarr avoid or reconsider now? A recent grab can explain why another report is not sent immediately. An imported release can prevent the same content from being selected again. A failed release can be remembered so the next candidate is not treated as if nothing had happened. The same event can therefore be useful to a reader diagnosing the past and to the decision engine controlling the future.

History is not a perfect account of the outside world. It records what Sonarr observed and what its own transitions established. If a file was copied outside Sonarr or a client lost an item before reporting its final state, the history may be incomplete. The source treats history as evidence that participates in decisions, not as proof that every external side effect occurred exactly as intended.

This distinction helps explain why the pre-grab and post-import systems keep provenance. A grab history entry can retain the source title, release quality, protocol, provider information, and download identity. An import history entry can retain the dropped and imported paths and the associated file. Later checks can compare the new candidate with the earlier event instead of relying on a current filename alone.

Blocklists stop the same failure from returning unchanged

When a release fails, Sonarr can create a blocklist entry for the series and episode set. For torrent releases, the entry can include the torrent information hash when available. For other cases, the comparison can use release title and related release information. The purpose is not to declare that a series or provider is bad. It is to prevent the same failed or equivalent release from re-entering the decision loop unchanged.

The decision engine checks the blocklist before allowing a candidate to proceed.