Diagnosing and Fixing Btrfs Snapshot Failures on AlmaLinux 9

Recognizable Condition

When you try to create or restore a Btrfs snapshot on AlmaLinux 9 and receive an error such as error code 5 or the mount reports Btrfs: filesystem is read‑only, you’re likely dealing with a snapshot‑related issue. These symptoms can stem from corrupted metadata, insufficient space, wrong mount options, kernel mismatches, or duplicate names.

Common Causes and Quick Diagnostics

Cause	Diagnostic Indicator
Corrupted metadata	btrfs check reports errors; dmesg | grep btrfs shows “Btrfs: failed to read metadata”
Insufficient space on underlying device	Mount fails with “Btrfs: filesystem is read‑only” or btrfs filesystem df shows unused space < 1 MiB
Wrong mount options (missing subvol=)	Snapshot not visible in btrfs subvolume list; /etc/fstab lacks correct subvol= entry
Kernel/driver mismatch	Recent dmesg entries contain Btrfs: unsupported feature or unknown inode type
Duplicate snapshot name	Creation command returns “snapshot already exists” or btrfs subvolume list shows duplicate names

Ordered Diagnostic Checklist

1. Verify filesystem and subvolume list
   Run

   sudo btrfs filesystem show

   to confirm the device is recognized and to list all subvolumes.
2. Inspect recent kernel logs
   Execute

   dmesg | grep -i btrfs

   . Look for error messages that point to metadata or driver problems.
3. Check free space on the filesystem
   Use

   sudo btrfs filesystem df /mnt/btrfs

   . Ensure there is at least 10 MiB of free space for snapshot operations.
4. Confirm mount options
   Open /etc/fstab or the relevant .mount unit and verify the subvol= option points to the intended snapshot or root subvolume.
5. List subvolumes to see if snapshot exists
   Run

   sudo btrfs subvolume list /mnt/btrfs

   . The snapshot should appear with its correct name.
6. Run an offline integrity check if errors were found
   If btrfs check reported problems, unmount the filesystem (sudo umount /mnt/btrfs) and run

   sudo btrfs check --repair /dev/sdX

   where /dev/sdX is the device containing the Btrfs volume.

Fixes Tied to Findings

• Corrupted metadata – After btrfs check --repair, reboot and verify with btrfs filesystem show that the subvolumes list is intact.
• Insufficient space – Extend the underlying LVM logical volume or move the snapshot to a different subvolume with more free space.
• Wrong mount options – Edit /etc/fstab to include subvol=/@ (or the appropriate path) and run

  sudo systemctl daemon-reload
  sudo systemctl restart local-fs.target

  or reboot.
• Kernel/driver mismatch – Upgrade to a kernel that fully supports Btrfs snapshotting (e.g., 6.6 or later). Verify with uname -r and cat /proc/filesystems | grep btrfs.
• Duplicate snapshot name – Delete or rename the conflicting snapshot:

  sudo btrfs subvolume delete /mnt/btrfs/old_snapshot

  and then recreate the new one.

Escalation Criteria

If you exhaust the checklist and still see persistent btrfs check errors, kernel panics during Btrfs operations, or data loss in critical directories, consider escalating to:

• AlmaLinux support forums or mailing lists for kernel‑specific bugs.
• Hardware support if SMART tests reveal disk errors.
• Professional data recovery services if the filesystem integrity is compromised.

Practical Verification

After applying a fix, confirm success by:

• Re‑running btrfs filesystem show to ensure the snapshot appears.
• Mounting the snapshot explicitly:

  sudo mount -o subvol=mysnap /dev/sdX /mnt/tmp

  and verifying file contents.
• Checking dmesg for any lingering Btrfs warnings.

Limitations and Precautions

• All commands assume AlmaLinux 9 with kernel 6.6 or later. Earlier kernels may lack full snapshot support.
• Running btrfs check --repair on a mounted filesystem is unsafe and can cause data loss. Always unmount or use a live environment.
• Changes to /etc/fstab require a reboot or a full reload of systemd units to take effect.
• Duplicate snapshot names are case‑sensitive; ensure uniqueness per subvolume.
• Disk health issues (e.g., SMART errors) can masquerade as Btrfs problems; run smartctl -a /dev/sdX before repair.

Example: Correcting a Missing subvol= Option

Suppose the snapshot daily-20241019 was created but is not visible because the mount points to the root subvolume. The fstab entry might look like:

/dev/sda1 /btrfs   btrfs   defaults,errors=remount-ro  0  0

To mount the snapshot, edit /etc/fstab to:

/dev/sda1 /btrfs   btrfs   defaults,subvol=daily-20241019,errors=remount-ro  0  0

Then reload systemd and restart the mount:

sudo systemctl daemon-reload
sudo systemctl restart local-fs.target

Verify with mount | grep /btrfs that the snapshot is active.