Recover a Damaged Btrfs Filesystem with btrfs rescue

You will identify the Btrfs failure, protect the original device, and run one btrfs rescue operation that matches it. Then you test whether the filesystem mounts again. Allow at least 30 minutes for preparation and verification. chunk-recover can take much longer because it scans the whole device.

This guide describes the installed btrfs-progs version 6.6.3 and its btrfs-rescue(8) manual page. Rescue commands modify filesystem metadata. They are not general-purpose substitutes for btrfs check, backups or forensic imaging.

1. Stop before writing to the damaged filesystem

Do not run a rescue command against a mounted filesystem. Stop services that use it, unmount every path that belongs to it, and finish or cancel any running replace or balance operation first. If the data matters, make a block-level copy or work from a suitable snapshot or clone before attempting repair. A rescue command can make later recovery harder if the diagnosis is wrong.

Use ordinary privileges to inspect mounts and identify the device. Use sudo only for the later operation that writes filesystem metadata:

$ findmnt -t btrfs
$ sudo btrfs filesystem show
$ btrfs --version
btrfs-progs v6.6.3

Record the exact device or devices belonging to the filesystem. A placeholder such as /dev/EXAMPLE below is deliberately not a value to paste unchanged. On a multi-device filesystem, do not assume that the first listed path is the only device involved.

2. Match the symptom to one rescue operation

Choose a command from the observed failure, not from its name. The installed tool provides these operations:

• fix-device-size addresses a stored device-size and superblock total-bytes mismatch that prevents a newer kernel from mounting the filesystem.
• zero-log clears the filesystem log tree when mount failure is caused by log replay. It can lose changes since the last transaction commit.
• clear-uuid-tree removes the UUID tree so the kernel can rebuild it at the next read-write mount.
• clear-ino-cache removes remnants of the old inode-cache feature.
• clear-space-cache v1 or v2 removes the selected on-disk free-space cache.
• super-recover attempts to recover bad superblocks from good copies.
• chunk-recover scans devices to rebuild the chunk tree and is the slowest, broadest operation here.

Read the kernel log and the mount error before selecting a command. For a log-replay diagnosis, look for open_ctree together with function names containing replay, recover or log_tree. A generic "cannot mount" message is not enough evidence for zero-log.

Check the exact syntax on this machine before using it:

$ btrfs rescue --help
usage: btrfs rescue <command> [options] <path>

    btrfs rescue chunk-recover [options] <device>
    btrfs rescue super-recover [options] <device>
    btrfs rescue zero-log <device>

The output is abbreviated above. It is a useful version check because newer upstream documentation may list commands that are not present in 6.6.3. Do not copy a command from a newer page without checking local help and the local manual.

3. Repair a device-size mismatch

Use this only when the error identifies a mismatch such as super_total_bytes and fs_devices total_rw_bytes. It changes device-size values so the kernel's stricter checks can pass. Replace the placeholder with the affected Btrfs device and run it while the filesystem is unmounted:

$ sudo btrfs rescue fix-device-size /dev/EXAMPLE
$ printf 'exit status: %s\n' "$?"
exit status: 0

Exit status 0 means the command succeeded; a non-zero status means it failed. It does not prove that every filesystem tree is healthy. Try a normal mount only after the command succeeds, and use a temporary, read-only mount target where possible:

$ sudo mkdir -p /mnt/btrfs-check
$ sudo mount -o ro /dev/EXAMPLE /mnt/btrfs-check
$ findmnt /mnt/btrfs-check
$ sudo umount /mnt/btrfs-check

If the mount still fails, preserve the error and stop selecting increasingly destructive commands at random. The undo is a backup or image taken before repair, not a second rescue command that reverses the metadata change.

4. Clear a log only when log replay is the diagnosis

zero-log is a targeted repair for a filesystem that fails while replaying its log tree. It can discard changes made since the last transaction commit, potentially up to the default commit period of about 30 seconds. Treat that as data loss, even if the filesystem mounts afterwards.

$ sudo btrfs rescue zero-log /dev/EXAMPLE
$ printf 'exit status: %s\n' "$?"
exit status: 0

After a successful run, attempt the read-only mount shown in the previous step. Check important files before returning the filesystem to service. If the command fails, do not repeat it in a loop. Keep the original kernel error, command output and image for further analysis.

5. Use the broader recovery commands last

super-recover and chunk-recover are not harmless probes. They write recovery data, and chunk-recover scans the whole device, so its run time depends heavily on device size. Both support -y, which answers yes to all questions. That option removes an opportunity to stop and should not be used in a first attempt.

$ sudo btrfs rescue super-recover /dev/EXAMPLE
$ printf 'exit status: %s\n' "$?"
exit status: 0

$ sudo btrfs rescue chunk-recover /dev/EXAMPLE
$ printf 'exit status: %s\n' "$?"
exit status: 0

Run only the command that matches your evidence, not both as a sequence. If prompts appear, read each one. Use -v when additional diagnostics are needed; the subcommand help marks its short form as a deprecated alias for the global verbose option.

The cache and UUID operations are also targeted metadata changes. Their documented forms are sudo btrfs rescue clear-ino-cache /dev/EXAMPLE, sudo btrfs rescue clear-space-cache v1 /dev/EXAMPLE, sudo btrfs rescue clear-space-cache v2 /dev/EXAMPLE and sudo btrfs rescue clear-uuid-tree /dev/EXAMPLE. Use them only for the corresponding feature or tree problem. The local binary's short help omits the operand for clear-uuid-tree, so follow the installed manual page and confirm with btrfs rescue clear-uuid-tree --help before acting.

6. Verify recovery and return to service carefully

A successful command is only the first checkpoint. Mount read-only, inspect representative directories and files, and record the kernel log. If the filesystem is usable and you have accepted any documented data loss, unmount it and restore normal service in a controlled maintenance window.

$ sudo mount -o ro /dev/EXAMPLE /mnt/btrfs-check
$ findmnt -no SOURCE,FSTYPE,OPTIONS /mnt/btrfs-check
$ ls -la /mnt/btrfs-check
$ sudo umount /mnt/btrfs-check

Do not delete the pre-repair image or replace the original disk until the files that matter have been copied and checked. If the repair did not restore access, stop and obtain filesystem-recovery expertise. Repeating repair commands can reduce the evidence available for a safer recovery attempt.