Instruction 02-download-categories-paths-and-arr-integration: Reading

An ARR workflow has two distinct storage responsibilities. The download client owns the download area, while Sonarr or Radarr owns the organized library. For example, a downloader may place a Sonarr job under /data/downloads/complete/tv, and Sonarr may import its episode into /data/media/tv/Series Name/Season 01. These locations should not be the same directory. If the library is used as the download destination, partial files, release names, unwanted extras, and unmanaged content can leak into the library.

A category is coordination metadata. Sonarr can submit a job with the category tv, while Radarr can submit one with movies. The downloader may use those categories to select completed paths, and each ARR application uses its configured category to recognize jobs that belong to it. Category spelling and case must agree between the applications. A category does not itself grant filesystem access, create a container mount, or teach ARR where a path exists.

When a download completes, the client reports both status and a path. ARR must be able to access that reported path in its own path namespace. On a native installation, both programs might see /data/downloads/complete/tv. In a well-designed container deployment, the host can expose a common parent such as /data to both containers at the same internal path. Sonarr then sees /data/downloads and /data/media exactly as the downloader does. This arrangement is easier to reason about and allows ARR to recognize that the download and library are on the same filesystem.

A remote path mapping is needed only when the download client reports a path that is valid for the client but not valid for ARR. A mapping is selected by the configured download-client host and replaces a remote path prefix with a local path prefix. For example, a client may report /downloads/complete/tv while Sonarr sees the same underlying directory as /data/downloads/complete/tv. The mapping translates the name; it does not mount storage, copy data, change ownership, or repair permissions. If both applications can be given a consistent path layout, that is generally preferable to adding mappings.

Hardlinks provide an efficient import method for torrents that must continue seeding. The original download name and the organized library name can reference the same underlying data. Hardlinks require the source and destination to be on the same filesystem. A path layout that places downloads and media beneath one shared storage root helps preserve this capability. Separate container mounts can make one physical filesystem appear fragmented to applications or can accidentally point to different filesystems. Comparing both the device number and inode number is the reliable basic check for two paths being hardlinks.

Usenet imports often move completed files because they do not need to remain available for seeding. Torrent imports commonly retain the source and create a hardlink when possible. If hardlinking is unavailable, an import can become a full copy, consuming additional space until the torrent is removed. ARR logs should be consulted to distinguish a successful hardlink, a copy fallback, a path-not-found error, and a permission failure.

The central troubleshooting sequence is therefore: confirm the job has the expected category; inspect the exact completed path reported by the client; verify that ARR can see that same data; confirm ARR can read the download and write to the library; check that source and destination are on the same filesystem if hardlinks are expected; and add a remote path mapping only when there is a genuine path-namespace mismatch. This sequence avoids random permission changes and unnecessary mappings.