Btrfs RAID Recovery & Filesystem Repair

Written by

Louis Rossmann

Founder & Chief Technician

Updated 2026-05-23

What Btrfs is and why it fails differently

Btrfs stores data in a B-tree structure where every block pointer carries a checksum. The filesystem keeps four copies of its superblock at fixed offsets: 0x10000 (64 KiB), 0x4000000 (64 MiB), 0x4000000000 (256 GiB), and 0x4000000000000 (1 PiB). When a NAS reports a crashed Btrfs volume, one or more of these superblocks has a mismatched generation number, or a tree block fails its checksum.

Because Btrfs is Copy-on-Write, it never overwrites a block in place. A new version is written elsewhere and the parent pointer is updated. This is why a sudden power loss during a write can leave a tree block pointing to a location that was never fully committed. The result is a parent transid verify failed error or csum failed in dmesg. The filesystem will not mount because the tree is internally inconsistent.

Why btrfs check --repair destroys data

The btrfs-progs tool btrfs check --repair attempts to rebuild broken trees by scanning the entire device and rewriting metadata. On a CoW filesystem, rewriting metadata means allocating new blocks and updating pointers. The old blocks are not erased, but the generation tree roots that pointed to them are overwritten. If the repair logic guesses wrong, you lose the historical roots that might have contained intact data.

Every recovery lab that recommends btrfs check --repair as a first step is gambling with your only remaining copies of the metadata tree. We do not run it on original drives. We image the drive first, then run read-only analysis on the image.

Why mount -o recovery,ro is not safe

The recovery mount option tells Btrfs to replay the log tree (the journal) at mount time. Even when combined with ro (read-only), the log replay writes updated pointers to disk. If the log contains references to corrupted blocks, the replay will write those bad pointers into the live filesystem structure. What started as a mountable degraded volume becomes completely unmountable.

The kernel documentation for Btrfs explicitly warns that the recovery option is not a forensic tool. It is a last-resort boot-time helper for a system that cannot mount normally. For data recovery, the only safe mount is a read-only loop mount of a forensic image.

Read-only forensic toolchain

Our workflow uses four read-only or image-based tools in sequence. We run these on copies of your drives, never the originals.

1. Imaging: Every drive is imaged with ddrescue or the PC-3000 Portable III before any filesystem access. A 4TB drive takes 6 to 10 hours at full speed.
2. Superblock inspection: btrfs inspect-internal dump-super /dev/image reads all four superblock copies and reports generation, total bytes, and root tree addresses.
3. Root search: btrfs-find-root /dev/image scans for historical tree roots with valid generation numbers. A Btrfs filesystem may contain dozens of older roots from before the corruption event.
4. Data extraction: btrfs restore -t <bytenr> /dev/image /output/ extracts files from a specific historical root. This is entirely read-only on the source image.

Btrfs RAID profiles and the write hole

Btrfs supports RAID 0, 1, 10, 5, and 6 natively. RAID 1 and 10 are stable and widely used. RAID 5 and RAID 6 inside Btrfs are not production-ready. The Btrfs RAID 5 implementation has a known write hole: if the system crashes during a parity update, the stripe is left partially updated. A subsequent scrub or read may use the wrong parity block to reconstruct data, silently corrupting it.

Synology, QNAP, and TrueNAS do not use Btrfs native RAID 5 for their primary storage pools. Synology SHR uses mdadm RAID 1/5/6 underneath Btrfs. QNAP and TrueNAS use mdadm or ZFS for the RAID layer and format the resulting volume with Btrfs or another filesystem. If you encounter a Btrfs RAID 5 array, it is likely a custom Linux installation, and the write hole is a real risk.

Consumer drives are rated for one unrecoverable read error per approximately 10^14 bits read, which is about 12.5TB. A 48TB RAID 5 rebuild has to read more than that, so the math says the rebuild will hit at least one error. When Btrfs RAID 5 hits a URE during a degraded scrub, it cannot reconstruct the stripe and the filesystem goes read-only or crashes.

Subvolumes and snapshots

Btrfs subvolumes are independent filesystem namespaces within the same partition. A snapshot is a read-only or writable subvolume that shares data blocks with its parent through the CoW mechanism. When a Btrfs filesystem is corrupted, the snapshot tree is often still intact even if the default subvolume is not.

Recovery means identifying which subvolume IDs are still reachable from a valid root. The btrfs subvolume list -t command on a mounted image shows the subvolume tree. If the default subvolume is damaged, we can extract data from an older snapshot by pointing btrfs restore at the snapshot's root bytenr.

Layered failures: Btrfs over mdadm

Most prosumer NAS devices run Btrfs on top of a software RAID layer. Synology SHR uses mdadm plus LVM plus Btrfs. Netgear ReadyNAS OS6 uses mdadm plus Btrfs directly. In these setups, the Btrfs corruption is often a symptom of an underlying RAID problem, not the root cause.

A degraded mdadm RAID 5 array that is missing one drive will still assemble in read-only mode with mdadm --assemble --readonly --force. Btrfs can then be mounted on the assembled array with mount -o ro,degraded. If the array was accidentally rebuilt (a drive was removed and reinserted, and the NAS started a rebuild), the parity is wrong and Btrfs checksums will fail across the entire stripe. In that case, we reassemble the pre-rebuild mdadm geometry from drive images and extract Btrfs from the original state.

Common Btrfs error messages

parent transid verify failed

A child tree block has a generation number higher than its parent expects. This usually means a torn write or a drive that acknowledged a write it did not complete. The filesystem will not mount.

csum failed

A data block or metadata block failed its CRC32C checksum. In a RAID 1 or 10 setup, Btrfs can read the mirror copy. In a single-drive or RAID 0 setup, the block is lost unless a historical snapshot contains an older version.

open_ctree failed

The kernel could not open the root tree. This is a catch-all error that appears when superblock inspection or root tree traversal fails. The underlying cause is usually a parent transid verify failed at the root tree level.

block group has wrong amount of free space

The block group's accounting metadata does not match the actual free blocks. This happens after an unclean shutdown on a nearly full filesystem. Btrfs refuses to mount because it cannot guarantee allocation safety.

Pricing

Btrfs recovery is priced per drive, multiplied by the number of drives requiring imaging and analysis. Standard consumer NAS drives use our HDD pricing tiers:

• File system recovery (logical): From $250
• Firmware repair (unrecognized / wrong size): $600–$900
• Head swap (clicking / beeping): $1,200–$1,500

Helium-filled enterprise drives (8TB and larger Toshiba MG, WD Ultrastar, Seagate Exos series) use helium-specific pricing: From $200 through $3,000–$4,500. A 5-bay Synology with four standard drives and one helium drive would be priced as the sum of the applicable per-drive tiers.

Rush service adds 100. +$100 rush fee to move to the front of the queue Donor drives are matching drives used for parts. Typical donor cost: $50–$150 for common drives, $200–$400 for rare or high-capacity models. We source the cheapest compatible donor available.

No diagnostic fees. No data, no recovery fee. If we cannot extract your files, you pay nothing for the recovery attempt.

How we recover it

Our lab is at 2410 San Antonio Street, Austin, TX 78705. Nationwide service is mail-in. We do not have satellite locations or franchise partners.

1. Intake & imaging: Every drive is forensically imaged with ddrescue or the PC-3000 Portable III. We do not touch the original drives with repair tools.
2. RAID reassembly (if applicable): For mdadm-based arrays, we assemble the RAID on a Linux workstation using the original drive order and mdadm superblocks. For Btrfs native RAID, we map the chunk allocation tree to determine which drives hold which stripes.
3. Metadata analysis: We inspect the superblock copies and run btrfs-find-root to identify valid generation trees. If multiple historical roots exist, we test extraction from each to find the most complete dataset.
4. Data extraction: Files are extracted with btrfs restore to a separate storage array. Extracted data is verified by checksum where possible.
5. Return: Recovered data is returned on an external drive or via secure download. The original drives and images are retained for 30 days, then securely wiped.

All work is performed in-house. We use named equipment including the PC-3000 Portable III, PC-3000 Express, DeepSpar Disk Imager, and a 0.02 micron ULPA-filtered clean bench for mechanical work. Founded in 2008.

Frequently asked questions

Can I run btrfs check --repair on a corrupted Btrfs volume?

No. btrfs check --repair overwrites historical generation tree roots on a Copy-on-Write filesystem. This destroys older metadata versions that might contain intact data. The safe approach is read-only extraction with btrfs-find-root and btrfs restore.

Is mount -o recovery,ro safe on a failing Btrfs drive?

No. The recovery mount option still replays the log tree, which writes to disk. On a degraded or corrupted Btrfs volume, any write risks updating pointers to bad blocks and making the filesystem unmountable. Always image the drive first and mount images read-only.

What does parent transid verify failed mean?

It means a Btrfs tree block has a generation number that does not match its parent's expected transaction ID. This indicates a torn write, an interrupted scrub, or a drive that dropped writes. The filesystem will not mount until a valid root is found with btrfs-find-root.

Does Btrfs RAID 5 have a write hole?

Yes. Btrfs RAID 5 and RAID 6 are not production-ready and contain a known write hole. If a crash occurs during a parity update, the stripe becomes inconsistent. A subsequent scrub may corrupt data rather than repair it. Synology and most NAS vendors avoid Btrfs RAID 5 for this reason.

How do I recover a Synology SHR volume with Btrfs?

Synology SHR is standard Linux mdadm plus LVM plus Btrfs. It can be assembled on any Linux workstation with mdadm --assemble --readonly. The Btrfs layer is then accessible with standard btrfs tools. No proprietary hardware is required. If a recovery lab tells you SHR is a black box only their proprietary tool can read, walk away.

What is the safe way to extract data from a corrupted Btrfs filesystem?

Image every drive first with ddrescue or PC-3000 Portable III. Then run btrfs inspect-internal dump-super to inspect metadata, btrfs-find-root to locate a valid generation tree, and btrfs restore -t to extract files. Never run btrfs check --repair or mount -o recovery on the original drive.

Can I just move the drives to a new NAS enclosure?

Only if the new enclosure uses the exact same RAID metadata format and drive order. Most NAS enclosures write their own configuration to the trailing sectors of each drive during initialization. Inserting your old drives into a new NAS often triggers an initialization that overwrites the mdadm or Btrfs superblocks, making recovery harder. Image the drives first, then experiment.

Why did my Btrfs RAID 1 volume crash if RAID 1 is supposed to be safe?

RAID 1 provides availability, not data protection. If both drives in a 2-drive RAID 1 have a corrupted Btrfs tree at the same logical offset, the filesystem has no good mirror to read. This can happen after a firmware bug, a simultaneous power event, or a bad RAM module that wrote incorrect data to both drives through the controller. The RAID layer did not fail; the filesystem layer above it did.

Are Btrfs snapshots a backup?

Snapshots are not a backup if they live on the same physical pool as the original data. A snapshot protects against accidental deletion or ransomware, but it does not protect against drive failure, controller corruption, or a fire in the server closet. A backup is a separate copy on separate hardware.

Do I need to send all drives if my NAS has a hot spare?

Send every drive that was part of the array at the time of failure, including the hot spare if it was ever activated. The Btrfs chunk tree and RAID geometry metadata are spread across all member drives. Missing one drive means missing part of the metadata tree, which can make the entire array unrecoverable.

How long does Btrfs recovery take?

Imaging takes 6 to 10 hours per 4TB drive. A 4-drive NAS typically takes 1 to 3 business days for analysis and extraction, assuming no mechanical failures. Drives with bad sectors or head degradation require additional time for bitwise imaging with the PC-3000.