Btrfs Scrub Guide: Data Verification, Auto-Repair, and Regular Maintenance

Sat, 09 May 2026 07:11:01 +0800

Btrfs scrub is one of the most important and most misunderstood Btrfs maintenance features. It is not fsck in the traditional sense. It is an online validation pass that reads filesystem data and metadata, verifies checksums, superblocks, metadata block headers, and disk read errors, and tries to repair damage when a known good replica exists.

If you use Btrfs on a NAS, home server, backup disk, or multi-device array, scrub should be part of regular maintenance. Its value is not “run it after disaster”. Its value is finding silent corruption early, while disks are still readable and good replicas still exist.

What scrub checks

According to the official Btrfs documentation, scrub scans filesystem data and metadata and mainly checks:

Data block checksum errors.
Basic super block errors.
Basic metadata block header errors.
Disk read errors.

On filesystems using replicated block group profiles such as RAID1, scrub on a read-write mount can automatically repair some damage. The repair is not magic recovery. Btrfs copies verified good data from another replica.

This is the key point: scrub repair depends on having a known good copy. On a single disk with only one copy of the data, scrub can detect checksum errors, but it usually cannot restore the original content by itself.

Common commands

Start scrub on a mount point:

`1`	`sudo btrfs scrub start /`

Run it in the foreground, useful for manual observation:

`1`	`sudo btrfs scrub start -B /`

Check status:

`1`	`sudo btrfs scrub status /`

Cancel a running scrub:

`1`	`sudo btrfs scrub cancel /`

Resume an interrupted scrub:

`1`	`sudo btrfs scrub resume /`

If you specify a Btrfs mount path, Btrfs scrubs all devices in that filesystem in parallel. If you specify a device, only that device is scrubbed. But if the replica on the specified device cannot be read or verified, Btrfs still tries to read a good copy from another device.

Scrub is not fsck

This is the easiest mistake to make. Scrub is not btrfs check, nor a traditional filesystem checker.

Scrub can:

Use checksums to detect data or metadata corruption.
Auto-repair when another reliable replica exists.
Detect disk read errors and some basic structural errors.

Scrub cannot:

Rebuild data when no good replica exists.
Replace offline filesystem checking.
Repair all complex tree-structure corruption.
Guarantee that application-level file contents are correct.

If filesystem structures are badly damaged, tools such as btrfs check may be needed under expert guidance. Do not treat scrub as a universal repair command.

NOCOW file risks

The Btrfs documentation calls out an important caveat: setting the NOCOW attribute with chattr +C currently also enables NODATASUM. That means the file data itself has no checksum.

Scrub can still validate and repair metadata for these files, but it cannot validate their data contents. This is especially risky in multi-replica setups: if one copy of a NOCOW file is damaged, Btrfs has no data checksum to tell which replica is good, so it may return bad contents to user space.

Some applications use +C by default for performance. systemd journal and some libvirt storage pool scenarios are notable examples. For VM images, databases, and log directories, this can make sense for performance, but it also means you cannot expect scrub to protect their data contents the same way it protects normal COW files.

Read-only scrub can still write

Another counterintuitive point: running read-only scrub on a read-write mounted filesystem can still cause some writes.

The official documentation explains that this is due to a design limitation around avoiding races between marking block groups read-only and writing back block group items. In other words, if you want scrub to perform no writes at all, you need to run read-only scrub on a read-only mounted filesystem. Adding a read-only scrub option on a read-write mount is not enough.

For normal users, this means:

Routine online scrub can run on a read-write mount.
For forensics, failure analysis, or very conservative read-only checks, confirm the mount state first.
Do not interpret read-only scrub as absolutely zero-write.

Interruption and resume

On newer kernels, scrub may be interrupted by events such as suspend, hibernate, filesystem freezing, cgroup freezing, and pending signals. After such an interruption, the running scrub is cancelled, but it can be resumed with btrfs scrub resume.

Scrub status is recorded under:

`1`	`/var/lib/btrfs/`

File names usually look like:

1
2

scrub.status.UUID
scrub.progress.UUID

The status file is updated periodically. A resumed scrub continues from the last saved position instead of starting completely over.

How often to run it

The official recommendation is once per month. In practice, adjust based on data importance and disk condition.

Common schedules:

Home NAS: once per month.
Backup disks: after long attachment sessions or once per month.
Important multi-device arrays: once per month, or more often if needed.
New disk migration or suspected disk problems: run immediately after migration.

Scrub may use around 80% of device bandwidth on an idle filesystem, so do not run it during peak workload. On HDD arrays, latency can rise noticeably during scrub. On SSDs, it still adds read amplification and background pressure.

Limiting scrub bandwidth

In the past, ionice was often used to reduce scrub impact on foreground I/O. The official documentation warns that this is not supported equally by all I/O schedulers. CFQ is no longer generally available. BFQ supports the relevant priority behavior, but you should understand it before using it. For common schedulers such as mq-deadline, cgroup2 I/O controller or Btrfs-specific limits are usually better.

Example using systemd to limit read bandwidth:

`1`	`sudo systemd-run -p "IOReadBandwidthMax=/dev/sdx 10M" btrfs scrub start -B /`

Since Linux 5.14, Btrfs can set per-device scrub limits through sysfs:

`1`	`echo 100m \| sudo tee /sys/fs/btrfs/FSID/devinfo/DEVID/scrub_speed_max`

Show current limits:

`1`	`sudo btrfs scrub limit /`

This setting is not persistent and disappears when the filesystem is unmounted. Replace FSID and DEVID with the actual values for your system. You can start by checking:

1
2

sudo btrfs filesystem show /
ls /sys/fs/btrfs/

Practical maintenance workflow

A reasonable Btrfs maintenance workflow can look like this:

sudo btrfs scrub start -B /
sudo btrfs scrub status /
sudo btrfs device stats /
dmesg -T | grep -Ei "btrfs|checksum|i/o error|read error"

If scrub reports corrected errors, Btrfs has repaired data from a good replica, but you should not ignore it. Continue checking disk SMART, cables, power, controllers, and Btrfs device stats.

If scrub reports uncorrectable errors, Btrfs could not find a good copy. Back up whatever can still be read, identify the affected files or device, and replace hardware or restore from backup as needed.

Summary

Btrfs scrub has a clear role: online data verification and replica repair. It is not fsck, and it is not backup.

It works best on Btrfs filesystems with checksums and redundant replicas, where it can regularly find silent corruption and restore from good copies. It cannot protect NOCOW file data without checksums, and it cannot recover damaged contents without a good replica.

If you store important data on Btrfs, run scrub monthly and use it together with SMART, device stats, backups, and alerting. Reliable data safety comes from checksums, redundancy, monitoring, and backups working together, not from a single command.

References:

Btrfs official documentation: Scrub

Data Verification on KnightLi Blog