Skip to content

Symlink Operations

A symlink stores another path; it does not contain the media bytes. If a mount moves, the link can remain present while its target becomes unavailable.

Choose an operation

Need Tool
Keep links in place but change target prefixes Prefix or preset rewrite
Move/copy the link files to another library tree Root migration
Record or restore link paths and targets Snapshot backup / restore
Keep recurring link snapshots Scheduled backups
Follow a known workflow transition Migration playbooks

Start with a dry run, inspect its scope, and keep a snapshot before applying changes. A symlink snapshot does not back up referenced media or application databases.

  1. Open the service whose library needs repair and select Tools → Symlinks.
  2. Choose a repair Playbook for the change you intend. Use a prefix rewrite when only the target path changed; use root migration when the link files themselves must move or be copied.
  3. Review the selected roots and old/new paths. Use paths visible inside DUMB, and limit the first run to the affected library.
  4. Select Dry run. Review the proposed changes, skipped links, conflicts, and errors before applying anything.
  5. Keep automatic backup enabled. Accept the acknowledgement and select Apply repair only for the reviewed change. Wait for the job's final result.
  6. Check a few repaired files in the relevant application's library and test playback. If results are wrong, stop and use the recorded backup manifest to restore before making another change.
flowchart LR
    Open[Open service Symlinks] --> Choose[Choose playbook and affected roots]
    Choose --> Preview[Run dry run and review changes]
    Preview --> Apply[Keep backup and confirm apply]
    Apply --> Verify[Check sample links and playback]

A successful link repair does not automatically change Sonarr/Radarr root folders or download-client settings. Review Arr paths when the library location changes.

In DUMB workflows, services like Decypharr, InfiniDysk, CLI Debrid, and Riven create curated symlink libraries that point to mounted content (for example rclone/DFS paths under /mnt/debrid).

This gives you:

  • Clean, curated libraries for media servers
  • Separation between raw mount trees and user-facing libraries
  • Faster migration paths when providers or mount layouts change

Common failure mode:

  • A symlink exists, but its target path no longer exists after mount/path changes.

Keep existing library paths

Existing NzbDAV paths remain active unless you deliberately complete the guarded namespace migration. Do not change a working mount or library path just to match an example below.

Technical details: container path model and retained legacy paths

Path model (high level)

Typical roots inside the container:

  • Raw/mount content roots:
    • /mnt/debrid/decypharr
    • /mnt/debrid/clid
    • /mnt/debrid/infinidysk
    • /mnt/debrid/riven
  • Curated symlink library roots:
    • /mnt/debrid/decypharr_symlinks
    • /mnt/debrid/infinidysk-symlinks
    • /mnt/debrid/clid_symlinks
    • /mnt/debrid/combined_symlinks
    • /mnt/debrid/riven_symlinks

Existing NzbDAV paths are retained

The paths above show the defaults for new InfiniDysk installations. The opt-in compatibility cutover does not move an existing /mnt/debrid/nzbdav mount or /mnt/debrid/nzbdav-symlinks library. Those paths remain active unless you explicitly select and complete the guarded full namespace migration.

Important:

  • Symlink targets are path-sensitive. If the target path changes, links may break until repaired/migrated.

Technical details: how each service produces its library

Supported service workflows

Decypharr

  • Arr requests route to Decypharr.
  • Decypharr resolves content in debrid-backed mount paths.
  • Arr rename/import behavior produces curated symlink results for library paths.
  • Common migration: provider-layout path rewrite (for example realdebrid/__all__ -> __all__).

InfiniDysk

  • Arr workflow uses InfiniDysk download-client flow.
  • Final libraries are curated symlink paths under InfiniDysk roots or combined roots.

CLI Debrid

  • CLI Debrid can create symlinks from mounted content into /mnt/debrid/clid_symlinks.
  • A frequent use case is cloning/migrating these entries into another symlink tree for downstream import workflows.

Riven

  • Uses configured symlink_library_path.
  • Included in backend defaults when configured.

Technical details: symlink API routes
flowchart LR
    Preview[Read-only repair plan] --> Review[Review proposed path changes]
    Review --> Apply[Submit async repair with backup]
    Apply --> Manifest[Record original links and targets]
    Manifest --> Rewrite[Rewrite or relocate selected links]
    Rewrite --> Status[Poll job status and verify result]
    Manifest --> Recovery[Restore manifest if recovery is needed]

DUMB provides three categories of symlink operations:

  1. Repair/migration (POST /api/process/symlink-repair)
    • Async apply mode:
      • POST /api/process/symlink-repair-async
      • GET /api/process/symlink-job-status
      • GET /api/process/symlink-job-latest
  2. Standalone snapshot backup/restore (POST /api/process/symlink-manifest/backup, POST /api/process/symlink-manifest/restore)
    • Compare/preview mode:
      • GET /api/process/symlink-manifest/compare
    • Async backup/restore modes:
      • POST /api/process/symlink-manifest/backup-async
      • POST /api/process/symlink-manifest/restore-async
      • GET /api/process/symlink-job-status
  3. Scheduled snapshot backup and restore selection (/api/process/symlink-backup-*)

See API details: Process Management API.


Repair modes (what each one does)

1) Prefix rewrite mode

Use when link targets changed path prefix but links should stay in-place.

Example:

  • From: /mnt/debrid/decypharr/realdebrid/__all__/...
  • To: /mnt/debrid/decypharr/__all__/...

Behavior:

  • Scans symlink entries in selected roots
  • Rewrites target strings that match from_prefix
  • Leaves symlink file location unchanged

2) Preset rewrite mode

Use for known migrations with built-in rules.

Current preset:

  • decypharr_beta_consolidated

Behavior:

  • Same as prefix rewrite, but rule set is predefined.

3) Root migration mode

Use when symlink files themselves must move between library trees.

Example:

  • From: /mnt/debrid/decypharr_symlinks/...
  • To: /mnt/debrid/combined_symlinks/...

Behavior:

  • Preserves relative path under the destination root
  • Supports:
    • move (default)
    • copy (copy_instead_of_move: true) for staged transition/import

Frontend option behavior (important details)

Roots behavior

  • Roots override replaces defaults for that run (it does not append).
  • Add root from common paths is a UI helper that appends selected paths into the Roots override textbox.
  • In current Symlink Repair UI:
  • choose a Playbook for common migrations, or custom modes
  • root override controls are shown for prefix-rewrite playbooks
  • preset rewrite playbook uses service-scoped defaults for the current service page
  • root migration playbooks use explicit from_root and to_root

Service-scoped defaults (repair UI)

On each service page, default repair scope is narrowed to that service root unless overridden:

  • Decypharr page -> /mnt/debrid/decypharr_symlinks
  • InfiniDysk page -> /mnt/debrid/infinidysk-symlinks
  • CLI Debrid page -> /mnt/debrid/clid_symlinks
  • Riven page -> symlink_library_path (or /mnt/debrid/riven_symlinks fallback)

Backup manifest on apply

Repair UI supports automatic backup manifest creation on apply runs:

  • Auto-backup enabled by default
  • If no explicit path is provided, a timestamped path is generated

This gives you rollback/audit artifacts without manual setup each run.


Snapshot backup / restore

Snapshot tab behavior:

  • Manifest path now includes a dropdown picker of existing snapshot files (same directory scan behavior as scheduled restore), plus a Custom path option.
  • Manifest path remains fully editable when Custom path is selected.
  • Restore flow includes Preview changes to compare the selected manifest against current symlinks using current restore options (overwrite_existing, restore_broken).
  • Backup root scope defaults to Current service root on the active service page.
  • Managed default manifest path now follows snapshot root selection:
    • current/specific root => /config/symlink-repair/snapshots/{service}.json
    • all default roots => /config/symlink-repair/snapshots/latest.json
  • Backup root scope supports:
    • Current service root
    • All default roots
    • A specific known root
    • Custom roots (textarea)

Registered backup destinations

Use the Backup destination selection in Snapshot backup or the schedule section to choose registered local/NAS archive storage. The legacy/local choice preserves your existing manifest path. A manual selection applies only to that backup; Save backup schedule explicitly saves its destination for future scheduled runs. Registering a profile or saving the global preference does not silently move existing custom paths.

Registered snapshots appear in the picker as managed artifacts. Their references are opaque identifiers, not paths or website URLs. Restore/compare verifies the recorded checksum and, when a service context is supplied, its process identity. Select an older registered destination explicitly when restoring one of its retained snapshots after changing the schedule's destination. A missing or changed mount reports an error instead of writing a local fallback.

Standalone backup

  1. Open Tools → Symlinks → Snapshot on the affected service page.
  2. Under Snapshot roots, keep Current service root or choose the exact roots you want to record. Review Manifest path for the saved snapshot.
  3. Choose whether to include currently broken symlinks, then select Backup snapshot now.
  4. Wait for completion, review the recorded-entry/error counts, and check that the snapshot is available in the Manifest path picker.

Restore from snapshot

  1. Select the intended snapshot under Manifest path. Use Refresh if a newly created snapshot is missing.
  2. Leave Restore dry run enabled. Review the overwrite and missing-target options, then select Preview changes when available, or Restore dry run.
  3. Check the projected restores, skipped entries, errors, and sample changes. Stop if the paths or counts are unexpected.
  4. Clear Restore dry run, accept the relink acknowledgement, and select Apply restore only after reviewing the preview.
  5. Wait for the result and test a few restored items in your application and media player. A restored link still needs its target storage to be available.
Technical alternative: snapshot backup and restore payloads

Standalone backup

Create snapshot manifest:

{
  "backup_path": "/config/symlink-repair/snapshots/latest.json",
  "roots": ["/mnt/debrid/decypharr_symlinks"],
  "include_broken": true
}

Restore from snapshot

{
  "manifest_path": "/config/symlink-repair/snapshots/latest.json",
  "dry_run": true,
  "overwrite_existing": false,
  "restore_broken": true
}

Recommended flow:

  1. Run restore in dry-run mode
  2. Review output
  3. Apply with confirmation when expected

Which button should I use?

Use Repair for target-prefix changes or moving/copying link entries. Use Snapshot backup before a change and Restore to review a retained manifest. Use Schedule for recurring snapshots.

Copy mode keeps the original link tree for a staged transition. Move mode removes entries from the source tree. Dry-run either choice and inspect the source, destination, target prefixes, and expected count before applying.

Scheduled backup behavior

  1. Open Tools → Symlinks → Schedule for the service.
  2. Turn on Enable scheduled symlink backup. Set Start time, Interval (hours), and Retention (count); zero retention keeps all matching snapshots.
  3. Review the saved path template and root scope, then select Save backup schedule.
  4. Check Next run. After that time, check Last run, status, and the available manifest list.
Technical alternative: scheduled symlink backup configuration fields

Enabled with service config keys:

  • symlink_backup_enabled
  • symlink_backup_interval
  • symlink_backup_start_time
  • symlink_backup_path
  • symlink_backup_include_broken
  • symlink_backup_roots (optional override)
  • symlink_backup_retention_count

  • Dev backup_destination_id (explicit registered destination; empty keeps the existing path)

Retention

  • symlink_backup_retention_count = 1 is the default when unset
  • 0 disables pruning (keep all matching manifests)
  • Values > 0 keep newest N, pruning older files matching the service template

  • Dev With registered storage, pruning applies only to that process's scheduled snapshots. Manual managed snapshots remain retained.

Default cadence

  • Default symlink_backup_interval is 168 hours (weekly) unless overridden.

Restore from scheduled backups

Use the Schedule tab dropdown to pick an available manifest discovered from the configured template.


Technical details: migration playbook payloads and steps

Migration playbooks

Playbook A: Decypharr provider path consolidation

Use preset rewrite:

{
  "dry_run": true,
  "presets": ["decypharr_beta_consolidated"]
}

Then apply:

{
  "dry_run": false,
  "presets": ["decypharr_beta_consolidated"],
  "backup_path": "/config/symlink-repair/decypharr-rewrite.json"
}
{
  "dry_run": false,
  "root_migrations": [
    {
      "from_root": "/mnt/debrid/decypharr_symlinks",
      "to_root": "/mnt/debrid/combined_symlinks"
    }
  ]
}
{
  "dry_run": false,
  "root_migrations": [
    {
      "from_root": "/mnt/debrid/clid_symlinks",
      "to_root": "/mnt/debrid/decypharr_symlinks"
    }
  ],
  "copy_instead_of_move": true
}

Use this when you want to seed/import existing curated content into another service’s expected symlink root without deleting originals.

{
  "dry_run": false,
  "root_migrations": [
    {
      "from_root": "/mnt/debrid/clid_symlinks",
      "to_root": "/mnt/debrid/decypharr_symlinks"
    }
  ],
  "copy_instead_of_move": false
}

Use this when you are done with the old tree and want a true move.

Use custom prefix rewrite on CLI Debrid root:

{
  "dry_run": false,
  "roots": ["/mnt/debrid/clid_symlinks"],
  "rewrite_rules": [
    {
      "from_prefix": "/mnt/debrid/clid/",
      "to_prefix": "/mnt/debrid/decypharr/__all__/"
    }
  ]
}

Notes:

  • This rewrites existing link targets in-place.
  • Exact to_prefix should match your active Decypharr mount layout.
  • Dry-run first to confirm expected match count.

Playbook F: Cross-service import seeding for Arrs

Goal: make existing non-Arr symlink libraries importable by Arr workflows.

Suggested sequence:

  1. Snapshot backup source + destination roots.
  2. Run root migration in copy mode (copy_instead_of_move: true) from source root to Arr-consumed root.
  3. Validate imports in Arr.
  4. Optionally run cleanup move/remove after stable import.

Playbook G: Combined root adoption without losing existing libraries

When switching to /mnt/debrid/combined_symlinks:

  1. Copy individual roots into combined root first.
  2. Update consumers/importers to combined root.
  3. Monitor and validate.
  4. Move or archive old roots after confirmation.

Playbook H: Recovery from bad apply

If an apply run produced unwanted results:

  1. Use the apply-time backup manifest (or latest snapshot manifest).
  2. Run restore with dry_run: true.
  3. If output looks correct, run apply restore.
  4. Re-run targeted repair only if needed.

Safe operating checklist

Before apply runs:

  1. Verify service and root scope (avoid broad accidental rewrites)
  2. Run dry-run first
  3. Confirm backup manifest path/auto-backup
  4. Apply with confirmation
  5. Validate sampled symlinks + Arr/media-server visibility

For large migrations:

  1. Snapshot backup first
  2. Prefer copy mode for staged cutovers
  3. Validate import behavior
  4. Switch consumers to new root
  5. Cleanup old root once stable

Short answer: sometimes.

Use this quick map:

  • Prefix rewrite only (targets changed, symlink root stayed the same):

    • Arr changes usually: No
    • Why: Arr still sees the same symlink path; only the underlying target changed.
  • Root migration/copy to a new symlink tree that Arr will now use:

    • Arr changes usually: Yes
    • Why: Arr import/root assumptions may still point at old paths.
  • Clone CLI Debrid symlinks into Decypharr tree for import seeding:

    • Arr changes usually: Yes (at least one-time import/discovery)
    • Why: Arr did not create these symlinks, so they are usually unknown to Arr until Manual Import (or equivalent discovery/import action).
  • Move from individual roots to combined_symlinks as primary workflow:

    • Arr changes usually: Yes
    • Why: completed import source path and/or related path mappings often need to align with combined layout.
  • Snapshot backup/restore only:

    • Arr changes usually: No
    • Why: this restores symlink state, not Arr configuration.

What to update in Arr when required

When you switch Arr-facing paths, review these in each Arr instance:

  1. Download/import source path assumptions

    • Ensure the path Arr receives from the download workflow is still valid after migration.
  2. Remote Path Mappings (when Arr sees different paths than DUMB)

    • If Arr runs in a different container/host namespace, update mappings so Arr can translate source paths.
  3. Root folders (managed library destination)

    • If your managed destination path changed, update Arr Root Folders for future imports.
  4. Manual Import source path (for seeding workflows)

    • For one-time seeding, point Manual Import at the copied destination tree (for example /mnt/debrid/decypharr_symlinks).
  5. Validation

    • Run one test import after migration.
    • Confirm no path mismatch warnings in Arr logs.
    • Confirm media server paths still resolve.

Practical examples

  • Example A: retarget_clid_mount_to_decypharr

    • Arr update: Yes (usually one-time Manual Import/discovery for existing items)
    • Reason: even if symlink paths are valid, Arr often has no item records for symlinks it did not create.
  • Example B: copy_clid_to_decypharr

    • Arr update: Yes (one-time Manual Import/discovery)
    • Arr update: Yes for ongoing workflow switches if path assumptions/mappings also change.
  • Example C: move_individual_to_combined

    • Arr update: usually Yes
    • Update source-path assumptions and any remote path mappings.

Troubleshooting

Symptom: Restore/repair shows no changes

Check:

  • Selected roots actually contain symlinks
  • Prefix/preset matches existing target strings exactly
  • You are not accidentally scoped to the wrong service root

Symptom: CLI -> Decypharr migration succeeds but Arr import still misses items

Check:

  • Arr download/import root actually points at the destination symlink tree.
  • Relative directory depth expected by Arr matches copied/moved tree.
  • Source links were copied (not moved) if you still depend on CLI tree.

Check:

  • from_prefix includes trailing slash behavior exactly as stored in symlinks.
  • Some links may point to mixed provider layouts; run additional rewrite passes if needed.
  • Include-broken setting may be excluding currently broken links.

Check:

  • Target paths exist in the same namespace the media server uses
  • Host/container bind mounts preserve expected absolute paths
  • Symlink targets resolve from the media server runtime context

Symptom: Scheduled backups not appearing

Check:

  • symlink_backup_enabled is true
  • Path template includes writable destination
  • Schedule status endpoint reports next/last run
  • Manifest list endpoint pattern matches your template

Symptom: Snapshot restore says manifest missing even though file exists

Check:

  • Snapshot Manifest path dropdown currently selected a real file and not Custom path with stale text.
  • Path exists inside the container namespace (not host-only path).
  • File permissions allow DUMB process user to read manifest.

Technical reference: symlink API routes

API references

  • Process Management API
  • /process/symlink-repair
  • /process/symlink-manifest/backup
  • /process/symlink-manifest/backup-async
  • /process/symlink-job-status
  • /process/symlink-job-latest
  • /process/symlink-manifest/restore
  • /process/symlink-manifest/restore-async
  • /process/symlink-manifest-files
  • /process/symlink-backup-status
  • /process/symlink-backup-manifests
  • /process/symlink-backup/reschedule

Related service pages: