Btrfs Scrub: Verify Checksums and Repair from Redundant Copies

Btrfs scrub reads allocated data and metadata, verifies checksums where available, and can repair a bad copy when another valid replica exists in the configured profile. Scrub is an online verification and repair operation, not a filesystem-wide consistency checker and not a substitute for backups. Its result depends on the device profile, checksum coverage, read errors, and whether the alternate copy is actually readable and valid.

The word “repair” is easy to overstate. A single-device filesystem generally has no independent replica from which to reconstruct corrupted data. A mirrored profile can provide another copy, while parity profiles have their own failure and recovery constraints. Scrub does not invent missing data, undo an application bug, or guarantee that a checksum collision is impossible.

Confirm the filesystem and device profile

Before starting work, identify the mounted Btrfs filesystem, all constituent devices, profile allocation, kernel, and tool version. A filesystem label or mount path is not enough to know its underlying device set. Inspect mounts and Btrfs device state without changing anything:

findmnt -t btrfs
btrfs filesystem show /mount/point
btrfs filesystem usage -T /mount/point
btrfs scrub status /mount/point

Replace the mount path with the actual filesystem. Device UUIDs, path names, and profiles may differ across machines. If a device is missing or degraded, do not start a broad scrub until the recovery plan is understood; additional reads can add load and may complicate an already failing device.

Btrfs stores data and metadata in chunks with profiles such as single, DUP, RAID1, RAID10, RAID5, or RAID6, subject to kernel and tool support. Data and metadata can use different profiles. The profile reported for one allocation class does not automatically describe every extent on the filesystem.

Checksums make verification possible

Btrfs checksums data and metadata unless a file or mount configuration disables checksums for the relevant data. Scrub reads extents, recalculates checksums, and compares them with stored checksum records. If a read fails or a checksum differs, the filesystem can seek a redundant valid copy where the profile provides one.

NOCOW files do not receive the same data-checksum protection as ordinary checksummed files. A scrub cannot validate content that has no checksum. Metadata checksums and data checksums should be discussed separately in the incident report. A device read error can be detected even when a data checksum is absent, but scrub cannot infer the intended bytes.

Checksums detect accidental corruption with high probability, but they do not verify application-level correctness. If the application wrote the wrong bytes and the filesystem checksummed them faithfully, scrub will report no problem. Use application checksums, database integrity checks, and backups for higher-level validation.

Online repair and redundancy boundaries

On a redundant profile, scrub can read another copy and repair a damaged copy when it can establish which copy is correct. This is the key distinction between verification and reconstruction. On a single profile with no replica, scrub can report an uncorrectable checksum or I/O error but cannot restore original content.

Parity profiles involve reconstruction and write behavior that should be checked against the deployed Btrfs version and profile implementation. A successful scrub status does not prove the device has no latent fault outside allocated extents or that future writes will succeed. Preserve error counts and device logs even when repair completes.

Do not mix scrub with balance, device replace, or filesystem repair commands in an improvised sequence. Each operation has different semantics and can add significant I/O. Establish a backup or snapshot plan, verify free space and device health, and schedule maintenance according to the service’s latency objective.

Scope and run scrub deliberately

Scrub can run on a mounted filesystem and consume substantial read bandwidth. Rate and concurrency options vary by btrfs-progs release. Check the local manual before limiting or resuming a job. Avoid starting overlapping scrubs on the same filesystem or launching a full read during peak service load without capacity planning.

Capture baseline status and kernel logs first. Observe per-device progress, bytes scrubbed, corrected errors, uncorrectable errors, and I/O errors. Correlate them with SMART or NVMe health, transport resets, multipath state, and storage-controller logs. A checksum error with no device I/O error points to a different path than repeated media read failures.

Do not clear device error counters merely to make the next report look clean. Record the old values and use time deltas. For a corrected error, identify which device copy was repaired and whether the source copy was independently verified. For an uncorrectable error, preserve file path or extent information and restore from backup or application-level replica rather than running random repair commands.

Scrub scheduling is an operational tradeoff. Running it continuously or too frequently can compete with foreground I/O, while leaving a filesystem unchecked for a long period increases the interval before latent damage is discovered. Choose a cadence based on device reliability, redundancy, capacity, workload, and the time required to finish a complete pass. A partially completed run is not equivalent to a full verification.

Multiple Btrfs filesystems on the same physical devices can share the same performance budget. Scrubbing each mount concurrently can multiply reads and queue depth. Use the filesystem’s status output to confirm whether a job is running, paused, or completed, and monitor block-device latency and application SLOs. Stop or rate-limit maintenance through the documented utility rather than killing the process and assuming the operation’s state is obvious.

After a device replacement or profile change, rerun scrub only when the topology is stable and the relevant data has finished relocating. A scrub during an active replacement can have different coverage and resource impact than a later full pass. Preserve the tool version and operation sequence so corrected error counts can be interpreted against the exact topology.

Scrub is not check, balance, or backup

Scrub verifies readable allocated extents and repairs using redundant copies. The offline check utility examines filesystem structures and has different operational risks; it should not be substituted for scrub on a mounted production filesystem. Balance relocates chunks and can change profiles or allocation layout; it is not a checksum repair command. Device replace copies data to a replacement device under its own procedure.

A snapshot is not a backup if it remains on the same failure domain. A checksum can show that a byte sequence changed, but recovery still requires a known-good replica. Maintain tested backups and document how to recover a file or full filesystem independently of the original device set.

Operational validation

After a scrub, verify the final status and review corrected and uncorrectable counts. Read a known file set or application dataset and run application integrity checks. Confirm the filesystem remains mounted, all devices are present, and no new transport or kernel errors occurred. Test alerts using synthetic status in a non-production environment rather than manufacturing disk faults.

An incident record should include filesystem and device UUIDs, kernel and btrfs-progs versions, data and metadata profiles, scrub start and end, throughput, status counters, kernel and device logs, repair actions, and subsequent application verification. Note which data classes lack checksums or redundancy.

Scrub is valuable because it reads data before an application happens to encounter a bad block, but its guarantees stop at the configured checksums and replicas. Run it with a known device topology, understand what can be reconstructed, and treat every correction as a hardware and data-integrity signal.

Related:

Sources: