Btrfs Scrub Found Uncorrectable Errors. What Now?

btrfs scrub reports Uncorrectable when it detected a bad read but could not repair that block from another verified copy. That result does not identify one universal fix. Preserve the scrub status and kernel messages, determine whether the damage belongs to file data, metadata or an unavailable lower layer, then recover from a known-good source. Do not reset the counters or run btrfs check --repair as a first response.

Scrub is an online validation pass, not a general filesystem repair program. The current Btrfs scrub manual says it validates checksummed data and metadata and can repair replicated blocks only by copying from a verified good replica. Exit status 3 specifically means that uncorrectable errors were found.

Uncorrectable has a narrower meaning than “Btrfs is broken”

Three counters in the result describe different events. Corrected means scrub found a trustworthy replica and rewrote the damaged copy. Uncorrectable means no verified copy could repair that read at the time. Unverified records a transient first-read failure where a retry succeeded. Each state needs a different incident decision; none proves by itself that an entire filesystem must be rebuilt.

Redundancy matters at the block-group level. Data and metadata can use different profiles, so “this filesystem is RAID1” is not enough evidence. Capture the actual allocation before deciding whether a good replica should have existed:

sudo btrfs filesystem usage -T /mnt/data
sudo btrfs scrub status -d /mnt/data

Single-copy data cannot be reconstructed by scrub from metadata redundancy. Conversely, a corrected error is still an incident signal: the good replica protected the read, but it did not explain why another copy became bad.

One more boundary is easy to miss. The NOCOW attribute normally implies NODATASUM for file data, so scrub cannot validate or repair those contents using data checksums. The official manual calls out systemd journal files and libvirt storage-pool directories as common examples. Check the actual file or directory rather than assuming every byte on Btrfs received the same checksum protection:

lsattr -d /path/to/object

Preserve the incident before another scrub changes the story

Start an evidence directory on storage outside the affected filesystem when possible. Record versions, the mount identity, the finished scrub result, kernel messages and device counters. None of these commands repairs or clears the incident.

uname -r
btrfs version
findmnt -no SOURCE,FSTYPE,OPTIONS /mnt/data
sudo btrfs filesystem show /mnt/data
sudo btrfs scrub status -d /mnt/data
sudo btrfs device stats -T /mnt/data

Next, export the relevant kernel window. Use the scrub start and finish timestamps rather than only the current boot tail; a long scrub can push the first useful line out of dmesg.

sudo journalctl -k --since '2026-08-05 01:00:00' --until '2026-08-05 03:00:00' | grep -E 'BTRFS|I/O error|nvme|ata|scsi|blk_update_request'

Replace the example times with the real window. Keep the unredacted output private because paths, device serials and workload names may be sensitive.

btrfs device stats --reset is not cleanup. The device manual defines counters for write, read, flush, corruption and generation errors. Resetting them only erases the old baseline. Save the values first; consider a reset only after the affected object and lower-layer cause have been handled, so any new increment becomes meaningful.

Name the damaged object—or record why it cannot be named

Modern Btrfs kernel messages may already include a subvolume root, inode, offset and path. When the path is present, capture it exactly and verify which subvolume exposes it. A pathname can later disappear while an extent remains referenced by another snapshot or reflink, so the kernel’s root and inode fields are part of the evidence.

When the log gives a logical address

If the message provides only a Btrfs logical address, logical-resolve can ask the filesystem which paths reference it:

sudo btrfs inspect-internal logical-resolve LOGICAL_ADDRESS /mnt/data

The inspect-internal manual documents this as a privileged logical-to-path query. Treat failure to resolve as evidence, not permission to invent a filename. The extent may be metadata, may no longer have a reachable path, or may need the original subvolume context.

When a path is reachable

Copy readable, high-value data to independent storage before experimenting. Reading the file can reproduce the checksum error, but a successful sha256sum proves only that the current bytes were readable and produced that hash. It proves integrity only when you compare it with a trusted earlier checksum or known-good package/image source.

For replaceable content, restore or regenerate the specific file from a verified source. Database files, virtual-machine images and application state require application-aware recovery; do not delete one extent from underneath a running workload. Use Proxmox restore drill evidence when the corrupted object belongs to a VM backup chain rather than an ordinary file.

When metadata is damaged or the filesystem turns read-only

Stop ordinary writes and protect the latest evidence. Structural corruption is a different branch from one unreadable data extent. The Btrfs check manual recommends unmounting before a structural check, notes potentially high memory and I/O use, and warns not to use --repair without developer or experienced guidance.

Filesystem type remains a hard gate. Hosts that report ext4 instead require ext4 offline repair; never transpose e2fsck, XFS or Btrfs repair commands across on-disk formats.

Recovery follows reachability and ownership, not a red counter

Reachable file data: preserve it, compare against a trusted copy, then restore or regenerate the narrow object. Rerun the workload’s own integrity check before returning it to service.

Unreachable data extent: retain the logical/root/inode evidence and examine snapshots, reflinks and subvolumes. If the filesystem remains readable, copy all recoverable important data out before removing references. If normal mounting is unsafe or impossible, btrfs restore can salvage files without modifying the source device, but its manual warns that recovered data can be incomplete or from an older version.

Metadata or mount failure: keep the source unchanged, work from a block-level clone where feasible and seek Btrfs-specific expert guidance. A read-only btrfs check can gather structural evidence on an unmounted filesystem; it does not turn --repair into a routine next command.

Lower device or array errors: Btrfs repair cannot fix a cable, controller, SSD, host storage path or md member. When Btrfs sits above Linux software RAID, Linux md recovery pacing is a separate lower-layer task with its own latency and verification budget. Do not start a balance merely to “move data away” from a suspected device; the Btrfs device manual warns that conversion can write new chunks onto the failing member and recommends device replacement for that ownership problem.

Provider-owned media: a VPS may expose only a virtual disk, so guest SMART data can be absent or meaningless. Preserve guest-visible Btrfs evidence and escalate with timestamps, logical addresses and device-stat deltas. When the physical layer is outside your account, managed hosting hardware diagnostics can continue below the guest boundary without replacing the filesystem receipt. Operators who control physical servers should document dedicated-server hardware inventory covering disks, controllers, RAID ownership and replacement paths.

Scrub is not a backup. Replicas inside one filesystem share administrative and failure boundaries, while a verified independent copy supports recovery when every local replica is bad. Choose object-lock backup design when retention needs a separate boundary, then prove it with restore testing and application-level verification.

Close on two independent receipts

The filesystem receipt and the device receipt answer different questions. Close the incident only when both are credible:

1. The affected file, metadata structure or workload has been restored, regenerated, salvaged or deliberately retired from every relevant snapshot/reflink path.
2. A new complete scrub finishes without uncorrectable errors; capture its exit status and per-device result.
3. The workload passes its own integrity check against a trusted reference, not merely a successful read.
4. Device counters remain stable through a representative observation window, or the lower failed device/provider path has been replaced and verified.
5. Independent recovery evidence proves that the next corruption event does not depend on the same Btrfs replicas.

A clean rerun is necessary but not sufficient. It proves the current reachable checksummed surface passed that scrub. Stable lower-layer evidence and a tested independent recovery path prove why returning the workload to service is reasonable.