⚙Leathery Tendons Would you believe… a sovereign AI stack, built in the open — Cecil Ray Burnett III

Unraid - Uncheck?

I CLAUDIUS FABULOUS SPEAK!

June 12, 2026

Unraid? – Uncheck — Technical Narrative

Source doc for video script. Why shfs broke my NFS workflow, and why TrueNAS fixes it.

CLAUDIUS FABULOUS

The Setup (who this happened to)

This is not a media-server workload. It’s constant small reads, writes, git operations, and file watches from multiple machines simultaneously. That distinction is the whole story.

The Symptom

Daily — sometimes multiple times a day — clients would hit:

Stale file handle

VS Codium sessions died mid-work. Claude Code crashed. The fix became a ritual:

sudo umount -l /mnt/ai && sudo mount /mnt/ai

A lazy unmount and remount, every day, sometimes mid-task. Workable for a hobbyist checking Plex. Not workable when AI agents depend on that mount being stable for hours of unattended work.

The Root Cause: shfs

Unraid’s signature feature — the “user share” — is what breaks this.

How Unraid presents storage: Unraid doesn’t pool drives at the filesystem level. Each data drive is an independent filesystem (XFS/BTRFS). The unified view at /mnt/user/ is synthesized by shfs, a proprietary FUSE (userspace) filesystem that merges the individual disks into one virtual tree.

Why that murders NFS: NFS is built on file handles — opaque, persistent identifiers the server hands clients so they can reference a file across requests without re-walking the path. NFS assumes file handles are stable: same file, same handle, across time and server restarts.

shfs can’t honor that contract:

  1. FUSE handles aren’t durable. A FUSE filesystem generates its file identifiers in userspace. When the shfs process restarts, rebalances, or the mover shifts a file between disks, the identifiers underneath the NFS export change.

  2. The file “moves” without moving. Unraid’s mover relocates files from cache to array disks. To shfs the path is unchanged; to the NFS layer, the underlying inode just teleported to a different filesystem. The handle the client holds now points at nothing → stale file handle.

  3. Two abstraction layers, one contract. NFS exports normally sit directly on a kernel filesystem with stable inodes. Unraid stacks NFS on top of a userspace merge layer. Every assumption NFS makes about the layer beneath it is violated by design.

This isn’t a bug Unraid can patch. It’s architectural. The forums are a decade deep in “NFS stale file handle” threads with the same non-answers: use SMB instead, set fsid, disable hard links, tune cache settings. They reduce frequency. None fix it, because shfs is the product.

Why It Doesn’t Hit Most Users

Casual workloads tolerate it. A Plex client that re-opens a file recovers silently. The failure surfaces when:

Run Linux clients doing real work over NFS, and you will meet shfs.

The Fix: Native ZFS (TrueNAS)

TrueNAS SCALE exports NFS directly from OpenZFS, a kernel filesystem:

The class of failure doesn’t exist on this architecture. That’s the trade Unraid makes and rarely advertises: mixed-size drive flexibility, purchased with a FUSE layer that breaks the oldest network filesystem contract in Unix.

What You Give Up Leaving Unraid

Fair is fair:

If your workload is media storage with occasional access, Unraid is genuinely fine. If your NAS is infrastructure that other machines work against — keep reading, this video was for you.

The Migration in One Slide

  1. Vet new drives (full SMART burn-in)

  2. rsync everything to a spare disk — then verify with a dry-run: zero delta or you don’t proceed

  3. Pull the backup disk out of the chassis

  4. Install TrueNAS to the internal boot device (UGOS/Unraid replaced)

  5. Build the pool: RAIDZ2 spinners + mirrored NVMe special metadata vdev

  6. Restore from the backup disk over direct USB

  7. Re-point clients at the new NFSv4 export — and never type umount -l again

Claudius Fabulous — Leathery Tendons Studios — own the compute, own the storage, own the keys.