# UnRAID Operational Gotchas

## Overview
 
Accumulated friction points from running UnRAID on Lusankya and integrating it with Centerpoint's Docker stack. Each entry includes root cause and the working fix.
 
## 1. NFS "Stale File Handle" After Mover Runs
 
**Symptom:** A client (Centerpoint) holding an NFS mount to a Lusankya share suddenly gets `Stale file handle` on `ls` or file access, requiring an unmount/remount to recover.
 
**Root cause:** When Mover relocates a file between cache and array, the underlying FUSE file ID changes. NFS clients cache file handles tied to the old fileid; UnRAID's `fuse_remember` tunable controls how long those handles are cached client-side, and a mismatch after a Mover-triggered fileid change produces "stale handle" until the client refreshes.
 
**Fix:**
- Force NFS **v4.2** on the client mount (NFSv3 is far more prone to this than v4.x).
- In `/etc/fstab` on the client, use `_netdev,nofail,x-systemd.automount,x-systemd.idle-timeout=300` rather than a static mount — automount re-establishes the handle on next access instead of hanging on a dead one.
- On the UnRAID side, the `fuse_remember` tunable (Settings → Global Share Settings) can be tuned if this happens frequently outside Mover events — but automount on the client side resolves it without touching server config.
## 2. Centerpoint Mounts Not Loading After Restart
 
**Symptom:** After a reboot, none of Centerpoint's NFS/CIFS mounts to Lusankya come back automatically; Docker containers depending on them fail to start.
 
**Root cause:** Docker services start before network mounts are ready at boot — a race condition, not a Lusankya-side fault.
 
**Fix:** `sudo mount -a` recovers immediately. To prevent recurrence, add `_netdev` to the relevant `/etc/fstab` lines so systemd waits for network availability before attempting the mount, and consider `x-systemd.automount` for more graceful boot-time handling.
 
## 3. Portainer 500 Error on Compose Redeploy After Changing NFS Path
 
**Symptom:** Updating a stack's NFS source path (new IP or mount point) in Portainer fails with a generic `Request failed with error code 500`.
 
**Root cause:** Docker refuses to redefine an existing **named volume's** `driver_opts` in place — the old volume definition with the stale NFS config is still registered.
 
**Fix:** Either `docker volume rm` the stale named volumes before redeploying, or — the more durable fix — replace named NFS volumes with direct bind mounts to an already-working host-level mount (`/mnt/data/...`) per the established Centerpoint convention of direct bind mounts over named volumes with `driver_opts`.
 
## 4. Immich / Any App Expecting Sentinel Files on a Pre-Existing Library Path
 
**Symptom:** An app (e.g. Immich) crashes on startup when its data volume points at a pre-existing directory rather than an empty one — it's looking for first-run sentinel files (`.immich`, etc.) that only get created during fresh initialization.
 
**Fix:** Manually create the expected subdirectories and sentinel files before first container start, with ownership matching the container's expected UID (commonly 1000).
 
## 5. UnRAID Array ≠ Traditional RAID 6
 
**Clarification, not a bug:** UnRAID's array uses per-disk XFS/BTRFS filesystems with a dedicated parity calculation layer — single parity drive here means tolerance for **one** failed data disk, recovered by rebuilding from the remaining disks + parity. This is functionally different from striped RAID 6 (which tolerates two failures by design). Don't assume RAID-6-equivalent fault tolerance when planning around this array; a second parity drive would be required to match that.
 
## 6. Cache-Only Shares Have No Mover Fallback
 
**Symptom:** None directly observed yet on this host, but worth flagging — `appdata`/`docker`/`system` are configured `shareUseCache="only"`. If the 2-disk BTRFS cache pool fills or both SSDs fail, there's no array fallback; writes simply fail.
 
**Mitigation:** Monitor cache pool free space proactively; don't let it run consistently above ~85% utilized.
 
## 7. Boot Flash / USB Enclosures Don't Report Standard SMART
 
**Symptom:** Diagnostics SMART reports for the boot flash drive and any USB-bridged drive come back empty — easy to misread as a tool failure.
 
**Root cause:** Most USB-to-SATA bridges and flash media don't pass through SMART attributes the same way native SATA/SAS does. This is expected, not a fault — but it does mean those devices have **no early-warning health signal**, so physical inspection / replacement-on-schedule is the only mitigation for the boot flash itself.
 
## Last Updated
2026-06-23