Btrfs RAID Recovery & Filesystem Repair

Written by

Louis Rossmann

Founder & Chief Technician

Updated 2026-06-29

What is Btrfs?

The kernel writes the primary superblock at 0x10000 (64 KiB) and mirrors it to 0x4000000 (64 MiB) and 0x4000000000 (256 GiB); BTRFS_SUPER_MIRROR_MAX is 3.

Only those locations that fall within the device size are written, so a smaller device carries fewer.

Btrfs is Copy-on-Write. When a tree block changes, Btrfs writes the new version to a newly allocated block & updates the pointers to it.

Why btrfs check --repair destroys data

The btrfs-progs tool btrfs check --repair tries to fix the problems it finds, & that means 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.

We do not run it on original drives. We image the drive first, then run read-only analysis on the image.

How Btrfs generation trees preserve older metadata

Btrfs generation trees preserve older metadata because Copy-on-Write writes new tree blocks and advances a root pointer instead of overwriting the old tree in place. A crash can damage the newest transaction generation while earlier roots still describe intact extents, snapshots, and directory trees.

The useful recovery target is not always the newest root. We compare generation numbers from btrfs inspect-internal dump-super against candidate roots reported by btrfs-find-root, then test extraction from images only.

btrfs inspect-internal dump-super /mnt/images/member-array.img
btrfs-find-root /mnt/images/member-array.img
btrfs restore -t <root_bytenr> /mnt/images/member-array.img /recovery/output/

How btrfs-find-root surfaces candidate roots

btrfs-find-root does not choose the recovery root by itself. It scans the imaged filesystem for root tree blocks and reports candidate bytenr, level, and generation values. We still have to match those candidates against the superblock generation & the chunk tree.

On Synology SHR and ReadyNAS OS6, that Btrfs layer usually sits above mdadm. We assemble the member images read-only first, then run Btrfs tools against the virtual array image. Running mdadm --create or btrfs check --repair before this step rewrites metadata that the root search depends on.

Bytenr

The byte address of a candidate root tree block inside the Btrfs address space. btrfs restore -t uses this value to read the root tree without modifying the source image.

Generation

The transaction number attached to a tree block. A lower generation can be more useful when the newest generation was interrupted by power loss or a dropped NAS member drive.

Level

The tree depth of the candidate block.

Why mounting a failing Btrfs drive is not safe

The first mistake users make is mounting a failing Btrfs drive read-write to look at the files.

For data recovery, the safe sequence is to image the device first with ddrescue or the PC-3000 Portable III, then inspect the image with read-only tools such as btrfs inspect-internal dump-super and btrfs-find-root.

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.
2. Superblock inspection: btrfs inspect-internal dump-super /dev/image reads the first superblock 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.
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.

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 QTS uses mdadm with LVM & ext4. QNAP QuTS hero & TrueNAS both use ZFS.

Consumer drives carry a worst-case specification of one unrecoverable read error per approximately 10^14 bits read, about 12.5TB. Real drives often do better than that, & the risk of an unrecoverable read error goes up with array size & drive age.

Because the Btrfs RAID 5 write hole makes degraded rebuilds risky, when the data is irreplaceable and unbacked we image every member read-only before any rebuild and reconstruct from the images.

Which Btrfs B-tree failed and what it means for recovery

Btrfs is not one flat structure. It stores its metadata in a stack of separate B-trees.

If the chunk tree is damaged, Btrfs loses the logical-to-physical map for every drive in the pool at once.

Root Tree (tree of tree roots)

When the root tree fails, you see failed to read tree root, open_ctree failed, or corrupt node: root=1.

Chunk Tree

Maps logical Btrfs addresses to physical device byte offsets, and tracks which physical drive holds each chunk in a multi-device array. Damage here destroys the logical-to-physical map, and the mount fails on the chunk root before it gets any further. btrfs rescue chunk-recover exists to rebuild that map by scanning the raw device, but it is slow on large devices.

Extent Tree

Tracks allocated space and reference counts for all data and metadata blocks. btrfs check --init-extent-tree is dangerous; recovery means read-only extraction with btrfs restore or deep lab reconstruction.

Checksum (csum) Tree

Stores the checksums (CRC32C by default) Btrfs uses to detect bit rot.

FS Tree / subvolume trees

The actual file and directory hierarchy: inodes, INODE_ITEM records, directory entries, and EXTENT_DATA references. btrfs restore can target an older FS tree root objectid and walk the directory tree cleanly without touching the array.

Log Tree

The journal for fsync operations. A damaged log tree blocks mounting. It can be cleared with btrfs rescue zero-log, which writes to disk and therefore only runs on a clone.

Device Tree

Holds the physical device mapping.

Free-Space Tree

Caches free-space tracking. We clear it with btrfs rescue clear-space-cache, on a clone.

btrfs check --readonly and btrfs rescue: what is safe on the original

btrfs check --readonly is the default, non-destructive diagnostic. It sits at the very start of a read-only workflow, before any btrfs restore attempt, and it does not modify the device.

It reports on root items, extents, free-space caches, csum items, and root refs. That output tells the technician which tree failed before anything writes a single byte.

The trap is escalating it to btrfs check --repair as a reflex. Repair should never be the routine next step after a read-only check. The check tells you what is wrong; it is not a license to let the same tool guess at fixing it.

Two flags go further than ordinary repair and are worth naming so you do not reach for them. btrfs check --init-extent-tree rebuilds the extent tree from scratch, and btrfs check --init-csum-tree recreates the checksum tree from scratch.

The btrfs-progs documentation labels both as dangerous: it warns not to use --init-extent-tree unless you know what you are doing, and warns against using --init-csum-tree blindly to fix checksum mismatch problems. We never run them on original media.

These three btrfs rescue subcommands write to disk, so they only ever run on forensic clones or images, never original client media:

Each of these is a write operation, which is why we clone first and run them against the clone.

Which structure these three subcommands rewrite is broken out one command at a time in the Btrfs corruption recovery walkthrough, next to the read-only root-tree work that runs before any of them.

When does partial recovery work?

Synology SHR is mdadm plus LVM plus Btrfs. We clone the members first, assemble the underlying blocks, then start Btrfs recovery on the assembled image.

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.

Recovery means identifying which subvolume IDs are still reachable from a valid root. On a mounted image, btrfs subvolume list shows you the subvolumes. 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

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. If you are staring at a crashed volume on a Synology or ReadyNAS, the box-specific steps live on our NAS-specific Btrfs corruption recovery page.

When the md array will not assemble at all, the fault sits below the filesystem. On a striped or parity array, Btrfs cannot mount until the mdadm superblocks and array geometry resolve into a single coherent block device underneath it.

What happens to a Btrfs native RAID-1 array when a drive goes missing?

When a Btrfs native RAID-1 array loses a device, the array can still be read, but only along a narrow safe path: a strictly read-only degraded mount run against drive images, never the originals. The reason a missing device is more fragile on Btrfs than on a hardware mirror comes down to how Btrfs places its copies.

Btrfs native RAID-1 is not the same thing as mdadm RAID-1. mdadm RAID-1 mirrors every block onto every member, so a 4-drive mdadm mirror holds four identical copies. Btrfs native RAID-1 keeps exactly two copies of each chunk on two different devices, no matter how many devices are in the pool.

Add a fifth drive to a Btrfs RAID-1 array and you get more capacity, not more copies. If you want three or four copies you have to ask for them explicitly with the RAID-1C3 and RAID-1C4 profiles. A single-device Btrfs filesystem sits at the other end of that scale: it defaults its metadata to DUP, two copies on the same disk.

That two-copies-on-two-devices rule is also why a degraded Btrfs RAID-1 array is dangerous to mount carelessly. If a degraded read-write mount has to allocate a new chunk & the remaining devices can't meet the RAID-1 requirement, Btrfs falls back to another profile such as single. That data has no redundancy. We do not test that on the original drives.

The safe extraction path is a read-only degraded mount on imaged members:

mount -o ro,degraded /dev/loopX /mnt/recovery

Image every member first, then mount the images read-only.

Before touching a mount at all, confirm what the array thinks it has. Two read-only btrfs commands show you the device set without changing it:

btrfs filesystem show

Lists the filesystem by UUID and flags a member that is registered but not present, so a missing device ID surfaces here before you mount anything.

btrfs device scan

Registers the devices that are actually present by UUID so the kernel can pair them into the right filesystem. It reads identities; it does not write array metadata.

How do you replace a failed Btrfs device without triggering a destructive rewrite?

Use btrfs replace. It rebuilds the data from a failed or missing member onto a new target device, using the RAID redundancy.

Use replace instead of btrfs device remove followed by btrfs device add. Remove can take a long time because it has to move all the data off the member you're removing, & add doesn't move any data by itself.

Both operations are online kernel operations that write to the array. In a recovery context they run on forensic clones or images, never on original client media, the same discipline the btrfs rescue subcommands demand above. This is the opposite of offline btrfs check --repair, which we never run on original drives at all.

A missing device is addressed by its numeric device ID, not a /dev/ path, because the path is gone once the drive dropped. Read the device ID from btrfs filesystem show, then point replace at it. The -r flag tells Btrfs to read from the source device only when a block exists nowhere else, so it prefers the other copy or parity wherever one is available:

btrfs filesystem show
btrfs replace start -r <srcdevid> <newdev> <mountpoint>
btrfs replace status <mountpoint>
btrfs replace cancel <mountpoint>

btrfs replace status reports progress and lets you confirm the reconstruction is reading cleanly. btrfs replace cancel stops it. Run these against the reconstructed clone, watch the status, and keep the original images untouched as your fallback.

Balance is the other post-failure operation people reach for, and it is easy to misread what its filters do. Balance filters such as devid, drange, stripes, and -dusage only select which block groups a balance run processes. They do not evacuate a specific failing member.

Moving data off a member is btrfs device remove, not a balance filter. If you want to watch or stop a running balance, the read-only status and the cancel command are:

btrfs balance status <mountpoint>
btrfs balance cancel <mountpoint>

None of this is a substitute for imaging first. Consumer drives carry a worst-case specification of one unrecoverable read error per roughly 10^14 bits read, about 12.5TB.

Real drives often do better than that, & the risk of an unrecoverable read error grows with array size & drive age. We image every member read-only before any replace or balance, then run those write operations against the images.

Common Btrfs error messages

Whichever of these messages you're looking at, btrfs check --repair writes to the disk, and it overwrites the older generation tree roots that read-only recovery reads from.

parent transid verify failed

A tree block does not carry the generation its parent expects; the kernel compares the two and reports what it wanted against what it found. The classic dropped-write case finds an older generation than wanted.

csum failed

A data block failed its checksum. In a RAID 1 or RAID 10 setup, Btrfs can read the mirror copy.

open_ctree failed

The kernel prints this when the mount sequence, open_ctree, fails. It's a catch-all error.

failed to read block groups: -5

The kernel prints this during open_ctree, the mount sequence that opens the filesystem's root trees, and it is followed immediately by open_ctree failed. The -5 is the kernel's errno for an I/O error, EIO. Two different faults land on that same number, and the split decides your next move. If the underlying block device is actually returning read errors, the first action is a read-only image of that member before anything else touches it, which is the same imaging-first order we follow on any multi-bay NAS recovery. If that device reads clean end to end, the errno is pointing at metadata that will not validate, and that is a forensic parsing problem against historical generations rather than a hardware one: btrfs-find-root to list candidate roots, then btrfs restore -t <bytenr> against the image. The userspace btrfs-progs tools print their own variant of the message, so the string turns up in dmesg & in tool output alike.

checksum verify failed

Emitted when a B-tree block fails validation on read. The message carries a tree level, & level 0 is a leaf node in the metadata tree. Under a native Btrfs RAID 1 profile, a scrub can rewrite the bad block from the mirror copy. Without a second copy on disk there is nothing to pull from. When Btrfs is sitting on a parity array, the bad block can also be arriving from the layer underneath it, which puts you in array-level recovery territory. Look at the filesystem with mount -o ro,nologreplay.

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: $1,200–$1,500

Helium-filled drives have their own pricing: $200–$5,000+. For a multi-drive array, we add up the per-drive tier that applies to each drive, then add the array reconstruction fee ($400-$800).

How that member-by-member total gets assembled, and how the RAID level on the array shifts it, is itemized in the NAS recovery cost breakdown.

+$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 read the chunk tree to determine which devices hold which chunks.
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.
5. Return: We return your recovered data on a target drive.

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 mounting a failing Btrfs drive read-write safe?

No. If the filesystem has a tree log, mounting replays it, & that writes to disk. The kernel does that even on a read-only mount unless you pass nologreplay. Always image the drive first. If you have to mount something, mount the image with ro,nologreplay.

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.

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. Synology says it chose Linux RAID instead of Btrfs RAID because of Btrfs RAID issues.

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 on the original drive, & never mount it read-write.

Why do older Btrfs generation roots matter during recovery?

Older Btrfs generation roots matter because Copy-on-Write writes new tree blocks instead of overwriting old ones. If the newest root points into a torn write, an earlier generation can still describe intact extents, snapshots, and directory trees.

How does btrfs-find-root help without repairing the filesystem?

btrfs-find-root scans the imaged device for candidate root tree blocks and reports their bytenr and generation values. It does not repair the filesystem. The recovery step is choosing a readable root, then extracting files with btrfs restore -t to separate storage.

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

Only if the new enclosure uses the same RAID metadata format, and only when the fault was the chassis itself, such as a dead power supply. If an interrupted mdadm sync or a Btrfs tree-root failure caused the crash, choosing Migrate or Repair tells the NAS to rewrite its system partitions and force-import the arrays. That frequently fails, and the NAS then offers a fresh install that overwrites the data partitions. 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. 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, 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.

Why does my Btrfs filesystem report open_ctree failed?

open_ctree failed is what the kernel prints when the Btrfs mount sequence fails. It's a catch-all error. A lab can use btrfs-find-root to find an earlier generation that's still valid, then extract the files read-only without risking more damage to the original drives.

Can btrfs check --repair fix a damaged extent tree?

No. btrfs check --repair should never be the routine fix. We image the drives first and use read-only extraction instead of destructive in-place repair.

What happens if the Btrfs chunk tree is corrupted on a RAID array?

The chunk tree maps logical data to physical locations across your RAID members. If it is destroyed, the filesystem loses track of where your files live on the physical disks.

Can I mount my degraded Btrfs RAID-1 to copy data off?

Only as a strictly read-only degraded mount, and only on drive images rather than your original disks. Image every member first, then run mount -o ro,degraded against the images.

If the warning is coming from the NAS interface rather than from btrfs itself, work out which layer reported it. On a Synology or ReadyNAS OS6 box, a storage pool that came up degraded is the mdadm array below Btrfs reporting a lost member, not the btrfs native RAID-1 state described above.

Does Btrfs RAID-1 keep a copy on every drive?

No. Btrfs native RAID-1 keeps exactly two copies of each chunk on two different devices, regardless of how many devices are in the pool. That is different from mdadm RAID-1, which mirrors onto every member. If you want three or four copies on Btrfs you have to use the RAID-1C3 or RAID-1C4 profiles, and a single-device Btrfs defaults its metadata to two copies on the same disk (DUP).

When should I use btrfs replace instead of btrfs device remove and add?

Use btrfs replace when a member fails or goes missing. It rebuilds the data directly onto the new device. For a missing device, point replace at the numeric device ID from btrfs filesystem show.

The other route, btrfs device remove followed by btrfs device add, works differently. Remove relocates the removed member's chunks onto the surviving members. Add then brings in the new disk without moving any data. In recovery, image every drive first & run either operation only on the clones.

How do I safely balance a degraded Btrfs array without losing data?

On original degraded media you generally do not. Balance is an online write operation. Image every member first, then restore redundancy on the clones by running btrfs replace onto a healthy target, and only balance the reconstructed copy.

Remember that balance filters only select which block groups are processed; they do not evacuate a specific failing member. Moving data off a member is btrfs device remove.