Why fsck.btrfs Does Nothing, and What to Run Instead

Boot logs mention fsck.btrfs, yet it never actually checks a Btrfs filesystem, and that surprises a lot of admins the first time they read the source. This guide covers when to ignore it, how to stop boot-time filesystem checks being scheduled for Btrfs, and where the real consistency-check command fits. On this machine the installed package is btrfs-progs 6.6.3-1.1build2, and the behaviour below is specific to that version and its fsck.btrfs(8) manual page.

Allow about ten minutes for the read-only checks and configuration inspection. You need a shell. Reading the current configuration and running the wrapper do not require elevated privileges. Editing /etc/fstab or checking a protected block device normally does.

1. Confirm which command is installed

Start with two ordinary, read-only commands. They avoid accidentally using a different script earlier in your PATH:

$ command -v fsck.btrfs
/usr/sbin/fsck.btrfs
$ btrfs --version
btrfs-progs v6.6.3

The name looks like a conventional filesystem checker, but the manual describes this program as a utility that exists for filesystem setup tools to call. It is a compatibility wrapper, not the Btrfs consistency checker.

Checkpoint: if command -v finds no executable, the package is not installed or the command is not in your PATH. Do not replace it with an unverified script copied from elsewhere.

2. See the no-op behaviour safely

Run the wrapper without a device. It prints a reminder about the real checker and returns success:

$ fsck.btrfs
If you wish to check the consistency of a BTRFS filesystem or
repair a damaged filesystem, see btrfs(8) subcommand 'check'.
$ printf 'status=%s\n' "$?"
status=0

The wrapper accepts the traditional -a, -A, -p and -y options too. The installed manual says these all have the same outcome: in non-interactive use the command exits successfully, otherwise it prints the message about btrfs check. None of them enable repair, replay a Btrfs log or inspect filesystem structures.

Do not interpret status 0 here as proof that a filesystem is healthy. It means the wrapper completed its compatibility job, nothing more.

3. Keep Btrfs out of automatic fsck passes

Traditional filesystems may need their fsck program after an unclean shutdown. Btrfs does not use this boot-time recovery pattern, so the manual says its fs_passno value in /etc/fstab should be 0. Inspect the file before changing anything:

$ awk '$1 !~ /^#/ && NF >= 6 { print $1, $2, "fs_passno=" $6 }' /etc/fstab

Identify the Btrfs entry from its mount point or filesystem type, then check the sixth field. A line might look like this:

UUID=REPLACE_WITH_UUID /srv/data btrfs defaults 0 0

The fifth field is fs_freq; the sixth is fs_passno. Do not change a line merely because it contains the word btrfs in a comment, and do not change the order of fields.

If the Btrfs entry has a non-zero sixth field, back it up first. This is a persistent boot configuration change, so use elevated privileges only for the edit:

$ sudo cp --preserve=mode,ownership,timestamps /etc/fstab /etc/fstab.before-btrfs-passno
$ sudoedit /etc/fstab

Set only the Btrfs entry's sixth field to 0. Save, then check the file's syntax without rebooting:

$ findmnt --verify --tab-file /etc/fstab

Check the exit status immediately afterwards. Status 0 means the entries could be parsed, but warnings can still identify permission limits or a configuration choice worth reviewing.

Recovery: if the check reports an error, restore the backup and investigate before rebooting:

$ sudo cp --preserve=mode,ownership,timestamps /etc/fstab.before-btrfs-passno /etc/fstab
$ findmnt --verify --tab-file /etc/fstab

A successful verification does not prove every mount option is appropriate, so keep the backup until the next planned reboot has completed cleanly.

4. Use btrfs check for an actual consistency check

When you need to examine Btrfs metadata, use the check subcommand of btrfs, not the wrapper. The safest starting mode is read-only:

$ sudo btrfs check --readonly /dev/mapper/REPLACE_WITH_BTRFS_DEVICE

Replace the obvious placeholder with the block device belonging to the filesystem. Establish the device first with tools such as findmnt and lsblk; do not guess from a partition number. The upstream Btrfs documentation recommends unmounting before a check, so schedule downtime and unmount the relevant filesystem first:

$ findmnt --source /dev/mapper/REPLACE_WITH_BTRFS_DEVICE
$ sudo umount /mount/point

--readonly prevents the checker from modifying the device. It does not make it harmless to run against the wrong device, and it does not make a mounted, actively changing filesystem a good target. A large filesystem can need substantial memory and time, so run the check from a maintenance window.

5. Do not jump to repair

The installed manual points to btrfs check for repair, but repair is a separate and potentially destructive decision. The upstream documentation warns against using --repair unless an experienced Btrfs developer or administrator has advised it, because no checker can repair every kind of corruption safely.

Warning: Do not turn a failed read-only check into this command as an automatic next step:

$ sudo btrfs check --repair /dev/mapper/REPLACE_WITH_BTRFS_DEVICE

That example is shown as a boundary, not a recommendation. Preserve the original device or a suitable image first, record the exact error, and obtain advice specific to the failure. Never use --force to bypass mount checks simply to avoid arranging downtime. If you unmounted the filesystem for inspection, mount it again only after the read-only work is complete and the device is known:

$ sudo mount /mount/point

Done means