Scrub a Btrfs Filesystem and Read the Error Report

Btrfs scrub walks every block on a mounted filesystem, checks it against its checksum, and repairs what it can from a good copy elsewhere. You will start one, read the status report properly, and know a corrected error from a real warning sign. The examples use btrfs-progs 6.6.3-1.1build2, installed on Ubuntu 24.04 here. Allow ten minutes to start and inspect a scrub, although a large filesystem can keep reading for hours.

You need a mounted Btrfs filesystem and root privileges for the usual start, status, cancel and resume commands. Replace /mnt/data below with the mount point you have checked. A scrub reads the filesystem heavily, so schedule it away from busy workloads. The local manual recommends monthly runs and estimates about 80% of idle device bandwidth.

1. Confirm the target is Btrfs

First identify the mount point and check its filesystem type. This is a read-only inspection and does not start a scrub:

$ findmnt -no TARGET,FSTYPE,SOURCE /mnt/data
/mnt/data btrfs /dev/mapper/example
$ sudo btrfs filesystem show /mnt/data
Label: 'archive'  uuid: 11111111-2222-3333-4444-555555555555
        Total devices 2 FS bytes used 1.20TiB

Do not substitute an arbitrary directory. btrfs scrub status / on a non-Btrfs root filesystem fails, as it does on this machine, with an error such as not a btrfs filesystem. The command needs a mounted Btrfs path, not merely a block device that happens to contain one.

2. Start a normal scrub

Run the scrub against the mount point:

$ sudo btrfs scrub start /mnt/data
scrub started on /mnt/data, fsid 11111111-2222-3333-4444-555555555555 (pid=12345)

Without options, btrfs scrub start backgrounds the operation and checks all devices in the filesystem. On replicated block-group profiles, such as RAID1, it attempts to repair a damaged copy using a verified good replica. This is a state-changing operation: it can write repaired blocks, and it will generate substantial read traffic.

Starting a second scrub normally does not start another pass while one is already running. Do not use -f as a general workaround. The manual reserves it for a damaged status file that falsely says a scrub is running.

Checkpoint: The start command should return successfully and show the filesystem ID. If it reports that the filesystem is not mounted, mount it through your normal storage procedure first; scrub cannot start on an unmounted filesystem.

3. Watch progress and inspect the last result

Ask for status while the scrub runs, or after it finishes:

$ sudo btrfs scrub status /mnt/data
UUID:             11111111-2222-3333-4444-555555555555
Scrub started:    Wed Apr 10 12:34:56 2024
Status:           running
Duration:         0:00:05
Time left:        0:00:05
Total to scrub:   28.32GiB
Bytes scrubbed:   13.76GiB  (48.59%)
Rate:             2.75GiB/s
Error summary:    no errors found

If no scrub is active, status reports the last finished or cancelled pass. The saved status is under /var/lib/btrfs/; it is updated every five seconds and is also what allows a cancelled pass to resume.

For a multi-device filesystem, add -d to separate the statistics by device:

$ sudo btrfs scrub status -d /mnt/data

The normal human-readable sizes use a base of 1024. Use --si if you specifically want decimal units, or --raw for byte counts. These affect presentation, not the scrub itself.

4. Interpret errors before taking action

A clean result includes Error summary: no errors found. A result such as this needs investigation:

Error summary:    csum=72
  Corrected:      2
  Uncorrectable:  72
  Unverified:     0

The detailed error labels distinguish checksum mismatches (csum), superblock errors (super), metadata header verification errors (verify), and blocks that could not be read (read). Preserve the output and investigate disks, cables, controller logs and backups when errors appear. A corrected block is evidence that damage occurred, not proof that the underlying device is healthy.

5. Choose read-only mode deliberately

Use -r when you want scrub not to attempt automatic correction:

$ sudo btrfs scrub start -B -r /mnt/data
Scrub device /dev/mapper/example (id 1) history
        scrub started at ...
        scrub finished after ...
        data_extents_scrubbed: ...
        error summary: no errors found

-B keeps the command in the foreground and prints final statistics, which is useful for a maintenance window or a script. Read-only scrub can run on a read-only filesystem, but the upstream documentation warns that -r on a read-write filesystem can still cause internal writes. Only a read-only scrub on a read-only filesystem avoids scrub writes entirely.

Do not confuse scrub with btrfs check. Scrub validates checksums and can repair damaged data or metadata only when a good replica exists. It does not perform the full structural checking of a filesystem checker.

6. Resume or cancel an interrupted pass

If a scrub is taking resources at the wrong time, cancel it cleanly:

$ sudo btrfs scrub cancel /mnt/data
scrub cancelled

The progress is saved. Resume from that position later:

$ sudo btrfs scrub resume -B /mnt/data

A successful previous scrub is not started again by resume; the command returns exit status 2 when there is nothing to resume. Do not delete files under /var/lib/btrfs/ to force a new pass. If you intentionally need a fresh scrub, use start after confirming that no scrub is active.

7. Check the exit status in automation

For a foreground run, capture the status immediately:

sudo btrfs scrub start -B /mnt/data
status=$?
case "$status" in
    0) printf '%s\n' 'scrub completed successfully' ;;
    3) printf '%s\n' 'scrub found uncorrectable errors' >&2; exit "$status" ;;
    1) printf '%s\n' 'scrub could not be performed' >&2; exit "$status" ;;
    *) printf 'unexpected scrub status %s\n' "$status" >&2; exit 1 ;;
esac

In the installed manual, status 0 means success, 1 means the scrub could not be performed, 2 means there was nothing to resume, and 3 means uncorrectable errors were found. A zero status is not a substitute for retaining and reviewing the status report.

Done means