Dennis HilkLinux Fix LabDE

Storage & Filesystems

Btrfs checksum failures and unreadable extents

Interpret Btrfs checksum reports with scrub results and redundancy, then preserve damaged data without assuming scrub can repair a single copy.

Editorial source review: Start with the evidenceShare this guide
On this page
  1. Symptoms & scope
  2. Possible causes
  3. Diagnose safely
  4. Evidence-guided next steps
  5. References & review
  6. Related problems

Symptoms & scope

  • A file returns EIO and the kernel reports csum failed.
  • Existing scrub status lists uncorrectable errors.

Relevant environment

Btrfs filesystems with checksummed data or metadata; NOCOW/NODATASUM files may have different coverage.

Recognizable messages (synthetic examples)
BTRFS warning (device sdb2): csum failed root 5 ino 812 off 0 csum 0x12345678 expected csum 0x87654321 mirror 1

Map inode and offset where possible; replica availability determines whether automatic repair is possible.

BTRFS error (device sdb2): checksum verify failed on logical 1048576 mirror 1 wanted 0x1234 found 0x5678 level 1

Metadata damage can affect many files; preserve an image and examine device and memory evidence.

Possible causes

These are possible explanations, not a confirmed diagnosis. Several independent faults can coexist.

  • Stored data differs from its checksum; media, transport, memory or software faults are possible and need independent evidence.
  • Redundancy can enable repair only when a valid alternative copy exists; a single device does not imply every metadata profile is single.

Diagnose safely

Run one command at a time in the relevant session. Read the explanation first. Uppercase placeholders need your own values; tools and privileges vary by distribution. These commands are displayed here and never executed by the website.

Check 1

Replace /mountpoint with the affected Btrfs mount. Read existing scrub results without starting a scan.

sudo btrfs scrub status /mountpoint

Interpret the result: Corrected errors mean a valid copy was used; uncorrectable errors require recovery from another source. No previous scrub result is not evidence of integrity.

Check 2

Read persistent Btrfs device counters. The command has no -z option and does not reset them.

sudo btrfs device stats /mountpoint

Interpret the result: Corruption errors support checksum concerns; read/write/flush errors indicate additional device I/O trouble. Compare changes over time because old counts persist.

Evidence-guided next steps

Preserve data and trace the failing path

When uncorrectable errors appear, preserve readable files and map any named damaged files to independent backups. Check device errors and memory stability before allowing new writes or automated cleanup.

Precautions: Do not silence errors by deleting checksum metadata or running btrfs check --repair. A checksum proves a mismatch, not the original correct byte value.

Recovery / rollback: Restore affected files from verified independent copies after the underlying fault is resolved; keep the original recovery image.

Did this solution help you?

Share this solution#

Plan scrub according to available redundancy

If storage is stable and backups exist, schedule a scrub to establish the scope. A normal scrub can repair from valid replicas; use read-only scrub mode for an assessment when modifications are not desired.

Precautions: Scrub creates sustained I/O and is not a structural filesystem checker. For an actively failing drive, rescue data before a full scan.

Recovery / rollback: Scrub repair has no general undo; retain backups. Cancel the scan if device errors grow and continue on a rescued copy.

Did this solution help you?

Share this solution#

References & review

This guide was prepared from primary project or distribution sources and reviewed on the date shown. This is an editorial source check, not evidence that a fix was reproduced on your hardware. Diagnostic log examples are synthetic fixtures. Version-dependent details must be checked against your installed release.