How I Swapped My Unraid Cache Drive for a Bigger BTRFS Mirror Without Losing My Mind (or My Docker Containers)

I’ve been running Unraid for a while now, and my single 128GB cache drive—formatted XFS—was starting to feel cramped. I picked up two shiny 512GB drives and decided to replace the old one with a BTRFS mirror. The goal was simple: keep the mount point at /mnt/cache so all my shares, Docker containers, and VMs would just… keep working. Seamless. Invisible. Easy, right?

Well, sort of. I learned a lot along the way, and I figured I’d write it all down in case someone else is staring at their server wondering if this is going to wreck their appdata.

The Plan That Sounds Too Simple

At first, I thought I could just pop the old drive out, slot the two new ones in, and tell Unraid to “replace” the cache. Nope. Here’s the first thing I learned: you can’t convert an XFS single-drive pool to a BTRFS multi-drive pool in place. Changing the filesystem means reformatting. That means the pool gets wiped. That means I had to move my data off, rebuild the pool, and move it back.

The good news? The name of the pool determines the mount point. Since I kept the pool named cache, it would still mount at /mnt/cache. That’s the “seamless” part—everything that points to that path would still find it after the swap.

But I had to be careful. My appdata is on the cache, and all my Docker containers depend on it. I couldn’t just copy files and hope for the best.

The Two Things You Must Save

I almost made a mistake here. I was laser-focused on my appdata folder and almost forgot about the other critical piece: the Docker vdisk image (docker.img).

See, your Docker setup is actually two separate things:

1. Appdata — the persistent configs, databases, and files your containers use.
2. docker.img — the virtual disk image that stores the actual container definitions and runtime state.

If you back up appdata but lose docker.img, you’ll boot up after the swap, enable Docker, and Unraid will cheerfully create a brand new, empty docker.img. All your appdata will still be there, but Unraid will have no memory of which containers existed or how they were configured. You’d have to recreate every single container from the “Previous Apps” tab. Not fun.

So my backup had to include both pieces. I went to Settings → Docker, noted the exact vDisk location (mine was under /mnt/cache/system/docker/docker.img), and made sure my backup strategy captured everything at /mnt/cache.

The Backup (And The Weird Size Surprise)

I disabled Docker and VMs first (Settings → Docker → No, Settings → VM Manager → No, then Apply). This is non-negotiable—you can’t copy a mounted docker.img while Docker is running.

Then I ran my rsync to the array:

mkdir -p /mnt/user/backup_cache
rsync -avh /mnt/cache/ /mnt/user/backup_cache/

Afterward, I checked the sizes with du -sh and got a confusing result: my backup folder was bigger than my cache drive. Like, noticeably bigger. I panicked for a second.

Here’s what I learned: sparse files. Virtual disk images like docker.img are created as sparse files. On the cache (XFS), they only physically consume the space that’s actually written inside them, but they report a large logical size. When rsync copies them to the backup destination, they can get fully written out, so the destination counts the full logical size. The backup looks bigger, but the data is identical.

To verify, I ran a checksum comparison:

rsync -avhc /mnt/cache/ /mnt/user/backup_cache/

The -c flag forces rsync to compare file contents. It finished with nothing to copy—meaning every byte matched. I also checked file counts:

find /mnt/cache -type f | wc -l
find /mnt/user/backup_cache -type f | wc -l

Same number. That was my green light.

The Actual Swap (Not a “Replacement”)

Here’s where I got hung up on the UI. I thought I’d select the new drives as “replacements” for the old cache drive. But that’s not how it works when you’re changing filesystems and drive counts. A drive replacement in Unraid is for swapping one drive into an existing, running pool. Since I was going from one XFS drive to two BTRFS drives, this was a fresh pool build, not a replacement.

So here was my actual sequence:

1. Stop the array in the web UI.
2. Shut down the server and physically pull the old 128GB drive.
3. Install the two new 512GB drives and boot back up.
4. In Main, the cache pool showed the old drive as “missing.” I clicked the red X to unassign it.
5. I set the cache pool Slots to 2, and assigned both new drives.
6. I changed the pool File System to BTRFS.
7. I started the array. The pool showed as unmountable, so I clicked Format.

After formatting, I confirmed the balance profile was set to RAID1 (the default for multi-drive BTRFS pools in Unraid). With two 512GB drives in RAID1, I get 512GB usable, mirrored. If I wanted the full 1TB, I’d need RAID0 or single mode, but I want the redundancy.

The Restore

I confirmed /mnt/cache was back and mounted (it was, because the pool name never changed). Then I restored:

rsync -avh /mnt/user/backup_cache/ /mnt/cache/

I re-enabled Docker and VMs. Everything came back exactly as it was—containers, configs, the whole works. Because both the appdata and the docker.img were restored to the exact same paths, Unraid didn’t know anything had changed except the underlying hardware.

I spot-checked a few containers, made sure my VM booted, and only then did I delete the backup folder from the array to reclaim space.

The Gotchas I’d Tell My Past Self

• Don’t skip the rsync -avhc check. The size discrepancy on sparse files will freak you out if you don’t verify by content.
• Move docker.img, not just appdata. Losing the vdisk means rebuilding every container template manually.
• You can’t “replace” the drive in the GUI when changing filesystems. Unassign the old (missing) one, assign the new ones, and format. It’s a rebuild, not a swap.
• Leave your backup on the array until you verify everything. The old drive is a nice-to-have fallback, but the real safety net is the array copy.
• Two drives in BTRFS RAID1 = 50% usable space. I knew this going in, but it’s worth repeating.

Was It Seamless?

For the containers and paths? Absolutely. /mnt/cache never changed, so nothing needed reconfiguration. The only “non-seamless” part was the downtime while I had Docker and VMs offline for the swap. There’s no way around that when you’re wiping the pool, but it was only an hour or so of actual work.

If you’re sitting on an old XFS cache and want to move to a BTRFS mirror, the process is well-documented in the Unraid forums and works exactly as advertised. Just be paranoid about your backup, verify it with checksums, and don’t forget the docker.img.

Your future self will thank you when all your containers just… start.