Check a Btrfs Filesystem Without Touching Repair

Run btrfs check read-only first, always, because its repair mode can turn a bad day into a ruined filesystem. This guide covers the read-only structural check, capturing its result, and the clear line between diagnosis and repair. The installed command is btrfs-progs 6.6.3 on this machine. Allow 10 minutes for a small filesystem, or much longer for a large one: memory use and runtime both grow substantially with size.

• You need to identify the block device or image to inspect, and an account that can read it.
• Privilege is conditional. You do not need root if device permissions already allow access; reach for sudo only when a permission error asks for it.

1. Confirm the installed command

Use the normal command name and check its version before trusting any example, including this one. None of this changes a filesystem.

$ command -v btrfs
/usr/bin/btrfs
$ btrfs --version
btrfs-progs v6.6.3
$ dpkg-query -W -f='${Package} ${Version}\n' btrfs-progs
btrfs-progs 6.6.3-1.1build2

• Syntax: btrfs check [options] DEVICE.
• btrfsck is an alias but deprecated: use btrfs check in scripts and runbooks.
• Multi-device filesystems get scanned as a whole. The checker follows every device belonging to the filesystem, so do not treat a different member path as a separate filesystem just because it is the argument you passed.

2. Stop writers and identify the device

Stop applications that write to the filesystem and arrange an unmounted check; the manual recommends unmounting first. Checking a mounted filesystem without --force is normally rejected, and adding --force to bypass that is not a harmless shortcut.

$ findmnt --target /path/to/mountpoint
$ lsblk -f

Replace /dev/DEVICE below with the actual Btrfs device: confirm it, do not guess from a familiar-looking disk name.

$ sudo findmnt --source /dev/DEVICE
$ sudo umount /path/to/mountpoint
$ findmnt --source /dev/DEVICE

3. Run the default read-only check

With the filesystem unmounted, run the checker with the safety boundary stated explicitly.

$ sudo btrfs check --readonly /dev/DEVICE
[1/7] checking root items
[2/7] checking extents
...
found 147456 bytes used, no error found

Phase labels, totals and exact wording vary with the filesystem and installed release. What matters is the exit status and whether the output reports errors.

$ status=$?
$ printf 'btrfs check exit status: %s\n' "$status"
btrfs check exit status: 0

Status 0 means the check completed successfully. A non-zero status means failure, but it does not by itself tell you that repair is safe. Save the complete output, including the command, device, date and package version, before asking anyone to interpret it. The default mode does not modify the device, and --readonly makes that intention explicit.

4. Switch to lowmem when resources run out

The default original mode reads metadata into memory and, on a large filesystem, can consume a great deal of RAM or run out entirely. If resource use is the problem, retry the read-only diagnosis in lowmem mode.

$ sudo btrfs check --readonly --mode lowmem /dev/DEVICE
$ status=$?
$ printf 'btrfs low-memory check exit status: %s\n' "$status"

lowmem trades memory for more I/O and usually a longer run. It is a diagnostic mode, not a repair mode: do not add --repair just because the original mode used too much memory. If the check is still impractical, move the device or image to a machine with suitable resources and preserve the original evidence.

5. Add focused checks only when justified

• --check-data-csum verifies data-block checksums, but expects the filesystem structure to already be sound and does not repair data from spare copies. Closer to an offline scrub than a general repair.
• --progress adds progress indications during a long run.
• --qgroup-report checks quota-group accounting.

$ sudo btrfs check --readonly --check-data-csum /dev/DEVICE
$ printf 'checksum check exit status: %s\n' "$?"

These options can lengthen the operation and do not turn a failed check into a repair workflow. Keep the output from each distinct command so an administrator can tell which test produced which finding.

6. Treat repair as a separate incident decision

The same boundary applies to --init-csum-tree and --init-extent-tree. Rebuilding a checksum tree is not a generic response to a checksum mismatch, and rebuilding the extent tree from scratch needs a specific understanding of the damage. Do not use either because a search result suggested it, or because a command needs to return zero.

7. Restore service and record the result

If you unmounted a filesystem and the check has completed, remount it only after reviewing the status and any maintenance alerts.

$ sudo mount /path/to/mountpoint
$ findmnt --target /path/to/mountpoint
$ df -h /path/to/mountpoint

If the check failed, leave the filesystem unmounted when that is safe for the service, retain the output, and escalate it with the device identity and version. Do not rerun a failing command with increasingly dangerous flags. A clean structural result does not prove every file is readable or that no hardware problem exists; it only answers the narrower question btrfs check asks.