Path Mapping

When Sonarr says /data/series/Frieren/Season 01/E01.mkv and Sublarr’s container only has /media/series/Frieren/Season 01/E01.mkv mounted, Sublarr needs to translate the prefix. Path Mapping is that translation table — one or more prefix-replacement rules applied to every path Sonarr or Radarr hands over.

When you need it

Setup	Need a mapping?
Sonarr, Radarr, and Sublarr in the same docker-compose mounting the same volume at the same path	No — paths already match.
Sonarr in one container at /data/series, Sublarr at /media/series	Yes — replace /data/series → /media/series.
Sonarr on a different host (NFS-mounted into Sublarr)	Yes — replace the remote path with the local mount point.
Standalone mode (no Sonarr/Radarr)	No — Sublarr reads paths directly from disk.

The mapping table

Each row is one prefix-replacement rule. Sublarr applies the longest-match rule per path, so more specific rules win over generic ones.

Field	Effect
Source prefix	The prefix Sonarr/Radarr uses. Match is on the leading part of the path string.
Target prefix	What to replace it with. Must exist inside Sublarr’s container.
Instance	Optional: limit this rule to one *arr instance. Useful when Sonarr-A and Sonarr-B mount different volumes.
Test	Type a path; the row shows the mapped output.

Trailing slashes are normalised — /data/series and /data/series/ are equivalent.

Where the values come from

Side	How to find it
Source prefix	Open Sonarr/Radarr → Series → any episode → “File path”. Take the path up to but not including the series folder.
Target prefix	Inside Sublarr’s container, run ls on the same series and copy the path up to the same point.

The two prefixes typically share a common suffix — that’s the part you keep. The differing leading parts are what the rule rewrites.

Examples

Sonarr path	Mapping	Sublarr path
/data/series/Frieren/...	/data/series → /media/series	/media/series/Frieren/...
Z:\Anime\Frieren\E01.mkv	Z:\Anime → /media/anime	/media/anime/Frieren/E01.mkv
\\NAS\series\Frieren\...	\\NAS\series → /mnt/nas/series	/mnt/nas/series/Frieren/...

Tip

Sublarr handles Windows-style backslashes and UNC paths on the source side, even though it itself runs in a POSIX container. Define the rule in whatever shape Sonarr/Radarr emits — Sublarr normalises during application.

Validating a mapping

The Test field at the bottom of the page lets you paste a real Sonarr/Radarr path and see exactly what Sublarr would translate it to. Three states are reported:

Result	Meaning
Mapped + path exists	Green — Sublarr can read the file.
Mapped, path missing	Amber — the mapping is correct in shape but the target prefix isn’t actually mounted. Check your Docker volumes.
No mapping rule matched	Red — the source prefix isn’t covered. Add a rule.

Common pitfalls

Symptom	Likely cause	Fix
Sublarr “can’t find” Sonarr episodes	Mapping prefix doesn’t match Sonarr’s actual paths	Use Test with a real Sonarr path to confirm.
Some series work, others don’t	Sonarr has multiple root folders; only one is mapped	Add a rule per root folder.
Mapping works for movies but not series	Wrong Instance filter	Set Instance to “all” or add a rule per *arr.
Path translation seems random	Multiple overlapping rules; non-deterministic order	Use the longest specific prefix; remove redundant generic rules.

Per-instance mappings

When you have several Sonarr or Radarr instances pointing at different roots, attach the mapping to a specific instance via the Instance dropdown. Sublarr applies only the matching rules — preventing a rule for “Sonarr-Anime” from being applied to “Sonarr-Western” media.

Where this is configured

Path Mapping lives at Settings → Connections → Path Mapping. The same dialog appears in step 4 of the onboarding wizard so you can set up the most common mapping while connecting your *arr instances.