btrfs

Identity

• Type: Kernel built-in filesystem (no loadable module needed on most distros)
• CLI tool: btrfs (subcommands: filesystem, subvolume, balance, scrub, device, quota, qgroup, check, defragment, rescue)
• Distro install: apt install btrfs-progs / dnf install btrfs-progs
• Filesystem created at: mkfs.btrfs time (not mounted separately)
• Kernel version matters: Significant stability improvements landed between 4.x and 6.x. Older kernels have known bugs — especially with RAID-5/6 and balance operations.

Key Operations

Expected State

• btrfs device stats /mount → all counters are 0 (any non-zero value is a read/write error)
• btrfs scrub status /mount → Status: finished with 0 errors
• btrfs balance status /mount → No balance found on '/mount' when idle
• btrfs filesystem usage /mount → Data and metadata ratios show reasonable allocation (metadata should not be >80% full)

Health Checks

1. btrfs device stats /mount → all counters 0; any non-zero value means hardware errors, act immediately
2. btrfs filesystem usage /mount → check both Data and Metadata sections; metadata ENOSPC is the most common silent failure
3. btrfs scrub status /mount → verify last scrub completed with no errors; schedule scrubs monthly via systemd timer or cron
4. btrfs subvolume list /mount → audit snapshot count; accumulation fills disk without appearing in normal df output

Common Failures

Pain Points

• ENOSPC due to metadata/data imbalance: The most common Btrfs "gotcha". Btrfs allocates space in chunks — if metadata chunks fill up, writes fail even when data chunks are available and df still shows free space. Fix: btrfs balance start -dusage=50 /mount to reclaim partially-empty chunks. This is not a bug — it is the expected behavior when chunk allocation becomes imbalanced.
• Mixed RAID profiles between data and metadata: Adding a second disk does not automatically mirror metadata. A system can have RAID1 data but single metadata, meaning metadata loss on one disk is fatal. Always explicitly set both with -d and -m flags.
• Snapshots are instant but they accumulate: Snapshot creation is O(1) and free. Deletion requires reference counting and can be slow. Unreferenced snapshots hold on to deleted data indefinitely — disk usage only decreases after snapshot deletion completes.
• btrfs check is slow and --repair is risky: Unlike fsck.ext4, Btrfs check does not have a safe repair mode. --repair can corrupt a filesystem that check reports as damaged. Prefer btrfs rescue subcommands (zero-log, fix-device-size) for targeted fixes.
• Btrfs RAID-5/6 has known parity issues: As of kernels through 6.x, Btrfs RAID-5 and RAID-6 have unresolved write-hole bugs. Do not use RAID-5/6 for data you care about. Use RAID-1 or RAID-10 instead.
• Send/receive for backups: btrfs send / btrfs receive is efficient for incremental backups using read-only snapshots as base references. Tools like snapper and btrbk automate the snapshot lifecycle and send/receive workflow — prefer them over manual scripting.
• CoW fragmentation on databases and VMs: Copy-on-write writes new data to new locations, which fragments sequential files over time. Use nodatacow mount option (or chattr +C) for VM disk images, database files, and other large randomly-written files. nodatacow also disables checksums for those files.

References

See references/ for:

• btrfs-options.md — mkfs and mount options organized by category
• common-patterns.md — filesystem setup, subvolume layouts, snapshots, rollback, backup, RAID, and compression
• docs.md — official documentation and community links