btrfs-rescue

Rebuild the filesystem metadata tree (very slow)

$ sudo btrfs [[resc|rescue]] [[ch|chunk-recover]] [path/to/partition]

$ sudo btrfs [[resc|rescue]] [[fix-de|fix-device-size]] [path/to/partition]

$ sudo btrfs [[resc|rescue]] [[s|super-recover]] [path/to/partition]

$ sudo btrfs [[resc|rescue]] [[z|zero-log]] [path/to/partition]

$ sudo btrfs [[resc|rescue]] [[c|create-control-device]]

btrfs rescue <subcommand> [<options>] <device>

chunk-recover
    Scans device to recover chunk tree metadata.
-y: Write recovered tree to disk (destructive).

super-recover
    Locates and recovers superblock copies from backups.
-y: Overwrite primary superblock with best copy.

clear-cache
    Clears potentially corrupted tree block caches.

-y
    Yes/confirm flag for destructive write operations.

btrfs rescue is a critical recovery utility in the BTRFS toolkit, used to repair corrupted core metadata structures on BTRFS filesystems. BTRFS employs redundancy for superblocks and extent allocation trees (chunk trees), but failures from power loss, disk errors, or kernel bugs can corrupt them, rendering the filesystem unmountable.

The tool offers targeted subcommands: chunk-recover scans the raw device to detect and reconstruct the chunk tree mapping logical block groups to physical locations; super-recover hunts for backup superblock copies (at 64K, 64M, 4G offsets) and verifies consistency; clear-cache wipes internal block caches that may hold stale data impeding mounts.

Operations are non-destructive by default, previewing fixes. The -y flag authorizes writes to disk. Invoke on unmounted devices only, ideally from live media. It's a bridge between btrfs check --repair failures and manual hex editing, often salvaging data without full backups. Success depends on preserved backups; always image the device first via dd. Part of btrfs-progs, it's essential for BTRFS admins handling production RAID or large volumes.

Use only on unmounted devices.
Image disk first (e.g., dd); -y can worsen corruption.
Not for mounted filesystems; may fail on encrypted/LVM devices.
Read-only mode safer for diagnosis.

Run without -y first to preview.
Combine with btrfs check --readonly for assessment.
For RAID, specify single device.

btrfs rescue chunk-recover /dev/sdb1 (dry-run)
btrfs rescue super-recover -y /dev/sdb1 (apply)

Added in btrfs-progs 0.20 (2011) amid early BTRFS stability efforts; refined in 3.12+ with improved scanners for larger drives.

btrfs(8), btrfs-check(8), btrfs-scrub(8), mkfs.btrfs(8)