Find Older Btrfs Tree Roots Before You Repair a Filesystem

You will inspect a Btrfs device for candidate tree roots and narrow the results by object ID, generation, or B-tree level. btrfs-find-root is a discovery tool: it reports metadata that may help a later recovery decision, but it does not repair the filesystem or select a root for mounting. Allow 10 to 15 minutes for a first check, longer if the device is large or producing read errors.

This guide describes the installed btrfs-progs version 6.6.3. You need the correct block device or filesystem image, and enough permission to read it. Reading a device may require sudo; writing the output to a normal working directory usually does not. Stop any repair or mount experiment until you have copied the important data and recorded the original device name.

1. Confirm the tool and identify the device

Check which executable will run, then confirm the package version:

$ command -v btrfs-find-root
/usr/bin/btrfs-find-root
$ btrfs-find-root --version
btrfs-progs 6.6.3-1.1build2

Replace /dev/mapper/storage-data below with the actual Btrfs device or an image file. Do not guess a partition from a similar name. Check it first with a read-only identification command:

$ lsblk -o NAME,TYPE,FSTYPE,LABEL,UUID,MOUNTPOINTS
$ file /path/to/filesystem.img

Checkpoint: the target should be the device containing the Btrfs filesystem, not a mounted subdirectory and not a random partition. If you are not certain, stop here and verify the storage layout with the system owner.

2. Run the default search

Pass one device argument. The default filters are level 0 and the root tree's object ID; the manual describes the generation filter as using the tree root's generation by default. The command reads metadata and prints candidate blocks on standard output:

$ btrfs-find-root /dev/mapper/storage-data
Superblock thinks the generation is 6
Superblock thinks the level is 0
Found tree root at 30588928 gen 6 level 0
Well block 30441472(gen: 5 level: 0) seems good, but generation/level doesn't match, want gen: 6 level: 0

The numbers above come from a small local Btrfs image and will differ on your device. Look for the superblock's expected generation and level, then for lines naming a block, generation, and level. A candidate described as 'seems good' is not a guarantee that the whole filesystem is healthy. Preserve the output in a text file for later comparison:

$ btrfs-find-root /dev/mapper/storage-data > find-root.txt
$ sed -n '1,20p' find-root.txt

Checkpoint: confirm that the command completed and that find-root.txt is non-empty. Its exit status is 0 when no error occurred and 1 when a problem occurred. A zero status is not proof that a reported candidate is mountable.

3. Search all metadata extents when the first result is not enough

Without -a, the program can stop once it has found the root it is looking for. Add -a when you need it to continue through all metadata extents, for example while comparing older candidates after an interrupted transaction:

$ btrfs-find-root -a /dev/mapper/storage-data > find-root-all.txt
$ sed -n '1,30p' find-root-all.txt

This can read substantially more metadata and may take longer. It still only reports what the tool finds. Do not treat -a as a repair switch, and do not write its output back to the device.

4. Narrow the search with filters

Use the numeric filters when the output is too broad or you are testing a specific hypothesis. -o selects the tree's object ID, -g selects the original transaction ID or generation, and -l selects the B-tree level:

$ btrfs-find-root -o 1 /dev/mapper/storage-data
$ btrfs-find-root -g 5 /dev/mapper/storage-data
$ btrfs-find-root -l 0 /dev/mapper/storage-data
$ btrfs-find-root -o 1 -g 5 -l 0 /dev/mapper/storage-data

These options filter the search; they do not change metadata and they do not request a different filesystem root to be activated. Use decimal integers, keep the device argument last, and record the exact command alongside its output. If a filter produces no useful lines, rerun the default search before concluding that the metadata is absent.

The level deserves special care. Level 0 is the default in the installed manual, but a higher level can be relevant when examining a different tree shape or a damaged structure. Do not invent a level from a block number. Use the level printed by the tool or supplied by a trusted recovery procedure.

5. Handle errors without changing the device

Capture the status immediately if a script or incident record needs it:

btrfs-find-root /dev/mapper/storage-data > find-root.txt 2>find-root.err
status=$?
printf 'btrfs-find-root exit status: %s\n' "$status"
if [ "$status" -ne 0 ]; then
    printf '%s\n' 'The search reported an error; inspect find-root.err.' >&2
fi

For a permission failure, rerun the same read-only inspection with elevated privilege only if your operating procedure allows it:

$ sudo btrfs-find-root /dev/mapper/storage-data > find-root.txt

Do not use sudo to make an output file in a directory where an unprivileged user should own it unless you intend to fix the ownership afterwards. For I/O errors, stop repeated scans and check the storage path, kernel log, and backup status. Repeated reads will not repair failing media.

6. Keep discovery separate from recovery

btrfs-find-root does not mount a filesystem, roll back a transaction, or write a recovered root. Do not follow a promising block number with an unreviewed mount, btrfs check --repair, or other write-capable operation. Those actions have different risks and should be chosen only after you have a verified backup or a forensic copy.

Keep the original device untouched while you compare the report with filesystem metadata and application records. If you are working from an image, preserve the image and write reports to a separate filesystem. The report itself can be removed later, but it is often useful incident evidence, so archive it with the command, date, package version, and device identifier.