NAS
Unraid Appdata Backup: Plugin + Restore Drill
Docker appdata holds the state of every container on the server — Plex databases, Sonarr/Radarr configs, Home Assistant data, Nextcloud sessions. Most operators have appdata on a Use cache: Only share, which keeps it fast but also means it lives outside parity protection. Without a separate backup, a cache disk failure takes every container's state with it.
Best for: Unraid operators running Docker containers with state worth keeping (Plex, *arr stack, Home Assistant, Nextcloud, databases, dashboards).
I'm here because… (find your section in 30 seconds)
- I just lost a container and need to know if I had a backup / what to restore → 'Restore drill — required, not optional' and 'Tool options' (the Appdata.Backup plugin keeps .tar.zst archives per container; restore is reverse).
- Unraid is warning 'share appdata set to cache-only, but files / folders exist on the array' → 'When Use cache: Only but files are stranded on the array' has the full 7-step Mover fix. Don't just dismiss the warning — stranded files mean partial appdata invisible to your containers AND your backup tool.
- I'm setting up appdata backup for the first time → 'First-time Appdata.Backup install (numbered steps)'. Apps tab > Appdata.Backup by Robin Kluth / Commifreak > follow the 7 steps. Skip the old CA Backup — it's EOL on Unraid 6.12+.
- My cache pool failed and I lost everything → 'Why appdata needs its own backup' explains what should have been backed up (and what now needs restore from backup, OR full rebuild if no backup existed). Read 'Retention and offsite' before doing this again.
- I want to know what to back up vs skip → 'What to back up and what to skip'. The 'pay special attention' list names the specific databases and state directories that need stop-the-container-first treatment.
- I'm choosing between Appdata.Backup, Borg, restic, rclone → 'Tool options'. Appdata.Backup is the right default for most operators; Borg/restic if you want dedup + encryption + offsite.
Why appdata needs its own backup
- Appdata typically lives on the cache pool with Use cache: Only — Mover never migrates it to the array, so parity never covers it.
- A single-disk cache pool failure means total loss of every container's state: Plex watch history, *arr download history, Home Assistant automations, password manager databases.
- Even on a redundant cache pool (BTRFS/ZFS mirror), you still have no protection against ransomware, accidental delete, or a container that corrupts its own database.
- Most container backup tools are appdata-aware and handle the stop-backup-start sequence safely; manual rsync without stopping the container risks copying a database mid-write.
What to back up and what to skip
- Back up: /mnt/user/appdata (full tree) including container configs, databases, and any state-on-disk that took time to set up.
- Skip: container temporary files, transcode scratch directories, and download/seedboxes if the data can be re-downloaded; these inflate backup size without value.
- Pay special attention to: PostgreSQL/MariaDB/SQLite databases (need consistent dump or container-stopped copy), Home Assistant .storage directory, Plex's Plug-in Support/Databases folder.
- Document which containers MUST be stopped before backup (anything with a live database) and which can be backed up running (stateless containers, static configs).
Tool options
- Appdata.Backup plugin (Community Applications search: 'Appdata.Backup' by Robin Kluth / Commifreak — the current maintained fork; supersedes the original CA Backup / Restore Appdata which is no longer maintained for Unraid 6.12+). Stops containers, snapshots appdata, restarts containers, writes to a destination share. Configurable schedule and retention. This is the right default for most operators.
- Borg or restic: scripted backups with deduplication and encryption; better for offsite or cross-server backups. Requires you to handle the container stop/start sequence yourself.
- rclone: for pushing backups to cloud storage (Backblaze B2, S3, Wasabi) after the initial appdata copy. Often combined with Borg/restic.
- Avoid: raw rsync against running containers with databases — likely produces an inconsistent copy that won't restore cleanly.
First-time Appdata.Backup install (numbered steps)
- 1) Apps > search 'Appdata.Backup' > Install. Confirm the maintainer shows as 'Robin Kluth' (Commifreak on GitHub) — this is the maintained fork, not the original CA Backup which is EOL on Unraid 6.12+.
- 2) Settings > Appdata Backup/Restore v2 > Settings. Set Backup destination to a share with Use cache: Yes (so backups land on cache fast, Mover migrates to array later for parity protection).
- 3) On the same Settings page, set Source = /mnt/user/appdata (the default). Compression = zstd (faster than gzip, comparable ratio).
- 4) Containers tab: tick the containers you want backed up. For each container with a live database (PostgreSQL, MariaDB, SQLite, Plex, Home Assistant), set Container settings > Stop container during backup = Yes. Stateless containers can stay running.
- 5) Schedule tab: pick a daily window when the server is idle (03:00 is common). Retention: 7 daily + 4 weekly is a sensible baseline.
- 6) Click Run backup now (top-right). Watch the log — it should report 'Backup successful' for each container. If anything fails, fix it before relying on the schedule.
- 7) Verify the destination: browse to your backup share and confirm one .tar.zst per container with today's timestamp. File sizes should be in the MB-to-GB range depending on container.
When 'Use cache: Only' but files are stranded on the array
- The error/warning 'share appdata set to cache-only, but files / folders exist on the array' means: the share is configured Use cache: Only (so Mover should never put files on the array), but Unraid found existing files for that share on array disks anyway. Common causes: cache pool filled up at some point and writes spilled to the array, or a container ran while the cache pool was unmounted, or the share was historically Use cache: Yes and Mover moved files before you changed the setting.
- Don't ignore it. Stranded array files mean some of your appdata is hidden from containers (which only see the cache pool) and unprotected by the backup process (which only reads /mnt/cache or /mnt/user/appdata at backup time, depending on tool). They're also taking up parity-protected array space for no benefit.
- Fix procedure: 1) Stop every container that uses the share (Docker tab > stop). This prevents writes during the move. 2) Shares > appdata > Edit > set Use cache: Prefer (not Only). 3) Main > Move Now (or wait for next Mover run). Mover now sees Prefer + files-exist-on-array and moves them array → cache. 4) Watch the Mover log until it reports finished. 5) Confirm: `du -sh /mnt/disk*/appdata 2>/dev/null` from a terminal should return zero or near-zero (only metadata). 6) Shares > appdata > Edit > set Use cache: Only again. 7) Restart the containers.
- If Mover refuses to move some files (typically open files held by a container you forgot to stop, or files with permissions Unraid can't read), Mover logs the path. Stop the holding container, run Mover again. If permissions are the issue, `chown -R nobody:users /mnt/disk*/appdata` from a terminal fixes it, then re-run Mover.
- If the cache pool is too small to receive all the stranded files (you over-committed), the right answer is a larger cache pool, not pinning appdata partly on the array. The 'cache-only but files on array' warning will return otherwise.
Restore drill — required, not optional
- Once a month, restore one container's appdata to a temporary location and start a copy of the container pointing at the restored data. Verify it boots, reads its database, and looks like the original.
- Document the restore steps for the most critical container (Home Assistant or Plex usually) so the procedure is known before you actually need it.
- If a restore fails, that backup is not a backup. Fix the backup tool or the procedure before moving on.
Retention and offsite
- Daily snapshots for 7-14 days is a reasonable baseline; some operators add weekly snapshots for another month.
- At least one copy should live off the cache pool — ideally on the array (Use cache: Yes share for backups) AND on an offsite/cloud destination.
- Ransomware protection: prefer cloud destinations with object-lock or versioning rather than mirror-style sync that propagates encryption.
Locate the appdata share and confirm its Use cache setting.
Shares > appdata (Use cache row)
Shares > appdata shows Use cache: Only (or Yes with a clear rationale).
Stop before pointing the offsite copy at the same account/MFA device as the local backup.
Layer path
Step-by-step runbook
Start here. Do each check in order, compare it to the expected result, and stop when the evidence explains the failure or the safe stop point applies.
Map appdata and identify state-bearing containers
Check: List every running container, its appdata path, and whether it holds a live database.
Expected result: You have a written list: stateless containers (safe to rsync running) vs database containers (must be stopped or use a tool that handles stop/start).
If not: Without this map, the backup procedure is inconsistent.
Install or configure Appdata.Backup
Check: Community Applications > install Appdata.Backup. Set source = appdata share, destination = a backup share on the array (Use cache: Yes recommended), schedule daily, retention 7-14 daily + 4 weekly.
Expected result: First scheduled run completes successfully and lists every container's appdata size.
If not: If the run errors on specific containers, those containers need stop/start config in the plugin's Advanced View.
Add an offsite layer
Check: Configure rclone or Borg to push the backup share to cloud storage (Backblaze B2, S3, Wasabi) or to a rotated external drive. Use credentials separate from the local backup.
Expected result: Offsite copy completes; cloud destination has the data.
If not: Without offsite, ransomware or loss of the home takes every copy.
Safe stop: Stop before pointing the offsite copy at the same account/MFA device as the local backup.
Run the first restore drill
Check: Pick the most critical container (Home Assistant or Plex usually). Restore its appdata to a temp path, start a second Docker container instance with that path mounted, verify it boots with the right data.
Expected result: Restored container is functionally identical to the original.
If not: If the drill fails, fix the cause before scheduling regular backups.
Safe stop: Stop before declaring backups working without a drill.
Document and schedule recurring drills
Check: Write down the restore steps and add a monthly calendar reminder to repeat the drill. Update the document when containers change.
Expected result: Procedure exists in written form; next drill is on the calendar.
If not: Without documented procedure, restore knowledge lives only in one person's head.
Decision tree
If: Container holds a live database (Plex, *arr stack, Home Assistant, Nextcloud, any *SQL).
Then: Inconsistent-copy risk if backed up while running.
Action: Use Appdata.Backup (handles stop/start automatically) OR stop the container manually before any rsync/snapshot/Borg job.
If: Container is stateless (reverse proxy, static config service).
Then: Safe to back up while running.
Action: Skip the stop/start step; rsync or Borg directly. Document which containers are in this category.
If: Cache pool is a single disk (no redundancy).
Then: A single disk failure is total loss of every container's state without a separate backup.
Action: Backup is non-negotiable: at least one local copy off the cache pool plus an offsite/cloud copy.
Safe stop: Stop adding new containers until the backup is in place.
If: Cache pool is a BTRFS/ZFS mirror (redundant).
Then: Protected against a single SSD failure, NOT against ransomware, accidental delete, or container DB corruption.
Action: Still need a separate backup; mirror is not a backup.
If: Restore drill failed (restored container won't start or shows wrong data).
Then: The backup tool, config, or destination has a problem.
Action: Treat this as a backup outage; do not move on. Common causes: stop/start not handling locks, permissions changed on copy, file path differs on restore.
Safe stop: Stop before adding more containers or changing schedule until the drill passes.
Evidence table
| Symptom | Evidence to collect | Likely layer | Next action |
|---|---|---|---|
| Plex starts fresh with no watch history after restore. | Restored to a temp path, started a second Plex container against it, watch history is empty. | Database file copied while server was running, ended up partial | Switch to Appdata.Backup which stops Plex during copy. |
| Sonarr/Radarr restored but doesn't recognize previous library. | Restored container shows empty library. | SQLite database copied mid-write | Stop the *arr container before copy; or use the tool's native backup export instead of file copy. |
| Backup destination filling up faster than expected. | Backup share growing GB/day; no retention policy applied. | Retention not configured; backups accumulating forever | Set Appdata.Backup retention to 7-14 daily + 4 weekly; older versions auto-pruned. |
| Backup completes but restore drill produces unbootable container. | Tool logs show success; restored container errors on start. | Permission or path mismatch on restore, OR container version drift | Document the restore path; pin container image versions next to the backup config. |
Commands and settings paths
Appdata location and cache setting
Shares > appdata (Use cache row)
Where: In the Unraid web UI.
Expected: Share is Use cache: Only and mount path is /mnt/user/appdata.
Failure means: Other settings (No / Yes / Prefer) produce performance and reliability problems for containers.
Safe next step: Set to Only after stopping containers and running Mover; restart containers after.
Appdata.Backup install status
Apps > installed > search 'Appdata.Backup'
Where: In the Unraid web UI's Community Applications interface.
Expected: Plugin is installed and has run at least once.
Failure means: If not installed, install it and configure: source = appdata, destination = a backup share on the array (Use cache: Yes), schedule daily.
Safe next step: Verify the first run in the plugin's log; do not move on until that succeeds.
Manual stop-copy-start for one container (verification)
docker stop <container> && rsync -a /mnt/user/appdata/<container>/ /mnt/user/<backup-share>/test/ && docker start <container>
Where: In an Unraid Terminal SSH session.
Expected: Container stops, rsync completes without errors, container restarts and runs normally.
Failure means: If rsync errors mid-copy or container fails to restart, the appdata path or permissions are misconfigured.
Safe next step: Use this only as a verification step; production backups should use the plugin, not raw rsync.
Restore drill
Restore an appdata folder to a temp path and start a second container instance against it.
Where: In Unraid > Docker (Add Container with same image, override appdata path to the restored copy).
Expected: Second container boots, reads its database, shows the same data as the original.
Failure means: Failure here is the backup-not-working signal. Investigate before trusting future backups.
Safe next step: Fix the root cause (stop/start config, permissions, path mismatch) and rerun the drill before scheduling additional backups.
Hardware and platform boundary
Change only when
- Upgrade to a redundant cache pool (BTRFS/ZFS mirror) after restore-drill evidence shows the backup chain is reliable; until then, capacity to actually back up is more important than mirror redundancy.
Evidence that matters
- SSD endurance for the appdata write workload, BTRFS/ZFS pool support, backup destination capacity (array space for the backup share), and a clear offsite target matter.
Evidence that does not matter
- Faster cache SSDs do not help the backup chain; the bottleneck is restore-drill discipline.
Avoid
- Avoid relying on a redundant cache pool 'as backup' — it protects against one SSD failure, nothing else.
Last reviewed
2026-05-07 · Reviewed by HomeTechOps. Reviewed for Unraid Docker appdata backup planning using cache-pool location framing, container-state classification, Appdata.Backup as the Unraid-native option, offsite layer requirement, and monthly restore-drill discipline.
Source-backed checks
HomeTechOps turns official docs and conservative safety rules into a shorter runbook. These links are the source trail for the page direction.
Planning a purchase?
We keep a source-backed, price-free comparison so you can buy once and right. No star ratings, every spec cited.
Synology vs UGREEN vs DIY NAS in 2026 →