From a Completed File to a Canonical Library

A download client can report completion without giving Sonarr a file that is ready for the library. This chapter follows Sonarr's second decision boundary: how a completed path is scanned, how evidence from the folder, filename, downloader, and media file is combined, and how an approved result becomes a durable episode file. The reader should be able to explain why import is not a copy operation, how an existing file is replaced safely, and where Sonarr stops and asks for human help.

The distinction follows directly from the earlier lifecycle. Before the download, Sonarr decided that a release was worth pursuing. During the download, an external client owned the transfer. After completion, Sonarr receives a new observation—a folder or file—and must decide whether that observation can change the canonical library. The fact that the client finished is useful evidence, but it is not enough evidence by itself.

A completed path is still untrusted input

The import service can receive a folder, a single file, or a root-folder scan. It first determines what kind of path it has and gathers the video files that might belong to it. A folder name can help identify a series, while a file name can supply season and episode information. But the service does not assume that every item below a completed path is a valid episode file.

It filters paths that belong to excluded system or extras locations and ignores known non-media patterns. It checks whether a file is locked when no download-client item is available to explain that the file is still being managed elsewhere. A locked file is not necessarily bad; it is simply not ready for a safe move or copy. The correct result is to try again later rather than racing another process.

File extensions create a separate safety boundary. The import service rejects dangerous, executable, user-rejected, and unsupported extensions before treating a path as media. This protects the transition from an arbitrary download folder into durable library state. A folder can contain archives, scripts, temporary files, samples, or unrelated documents alongside a video. Importing everything because it sits beneath a completed path would make the folder boundary an unsafe trust boundary.

The service also checks ownership of the destination context. If an import folder is already mapped to an existing series folder, Sonarr refuses to process it as an external import. The same path can have different meanings depending on whether it is a drop location or the library's own canonical location. Rejecting that overlap prevents the import process from confusing an existing series with a new source.

Series resolution is another gate. When a folder or file is processed without a series supplied by the caller, Sonarr uses the cleaned folder or file name to find one. If no series is known, the result is an unknown-series rejection. When a series is supplied, the path still has to produce files that can be mapped to that series. A known destination does not make an arbitrary file an episode of that series.

Multi-season downloads receive an explicit conservative treatment. A completed folder can contain more than one season, and automatically assigning every file to one series path can create incorrect episode links or an incomplete import. The service returns a multi-season rejection rather than silently guessing. Partial season packs and season extras receive similar treatment later in the decision process. These are not cosmetic exceptions; they are cases where the folder's apparent completeness does not match the library's episode-level model.

Import is a second decision engine

After the initial safety and path checks, Sonarr constructs a local episode candidate for each video file.