AlmaLinux 9: repairing a damaged XFS

Test scope

A 512 MB loop disk in an AlmaLinux 9.8 privileged container (host kernel 5.14.0-687.54.1.el9_8): mkfs.xfs, mount and write a file, run xfs_repair while mounted, run xfs_repair -n after unmounting, corrupt the superblock magic, run the real xfs_repair, remount and read the file. Log: plans/content-expansion/evidence/logs/alma-xfs-repair.log.

Repairing a production volume (with backups, snapshots and a maintenance window) is out of scope; this page covers command behaviour and the order of decisions.

Step 1: make sure it is not mounted

mount /dev/loop0 /mnt/x
sudo xfs_repair /dev/loop0

xfs_repair: /dev/loop0 contains a mounted and writable filesystem

fatal error -- couldn't initialize XFS library

As long as the filesystem is mounted writable, xfs_repair refuses. That is protection, not a bug: repairing metadata while the mounted kernel still holds old cache and journal state makes things worse.

Step 2: dry-run with -n first

sudo umount /mnt/x
sudo xfs_repair -n /dev/loop0

Phase 7 - verify link counts...
No modify flag set, skipping filesystem flush and exiting.

-n scans without writing; in production capture that output before deciding to repair for real.

Step 3: recognise a bad superblock

sudo dd if=/dev/zero of=/dev/loop0 bs=4 count=1 conv=notrunc
sudo mount /dev/loop0 /mnt/x

mount: /mnt/x: wrong fs type, bad option, bad superblock on /dev/loop0, ...

The first four bytes are the XFS magic (XFSB). Zero them and the kernel no longer sees a filesystem, so mount reports bad superblock; xfs_repair -n then says the primary superblock would need modifying, which -n will not do.

Step 4: repair and fall back to the backup superblock

sudo xfs_repair /dev/loop0

Phase 7 - verify and correct link counts...
Note - stripe unit (0) and width (0) were copied from a backup superblock.
done

XFS keeps superblock copies across the disk; repair overwrites the damaged primary with a backup. The Note means geometry was copied from the backup — if the volume had stripe settings, correct them as the message suggests.

Step 5: mount and verify the data

sudo mount /dev/loop0 /mnt/x
cat /mnt/x/a.txt

hello

The repair only counts as successful when the filesystem mounts and key data reads back. done alone is not proof.

Common traps

• Repairing while mounted: refused outright; stop the workload and unmount, or repair a snapshot copy elsewhere;
• Treating -n as a repair: it writes nothing;
• Ignoring the stripe note: geometry restored from a backup can lose stripe settings and hurt performance.

Practice: reproduce a repair on a loop disk

sudo dnf install -y xfsprogs
truncate -s 512M /var/tmp/x.img
L=$(sudo losetup -f --show /var/tmp/x.img)
sudo mkfs.xfs -q "$L"
sudo mkdir -p /mnt/x && sudo mount "$L" /mnt/x
echo hello | sudo tee /mnt/x/a.txt >/dev/null && sync
sudo umount /mnt/x
sudo dd if=/dev/zero of="$L" bs=4 count=1 conv=notrunc
sudo xfs_repair "$L" | tail -3
sudo mount "$L" /mnt/x && cat /mnt/x/a.txt

Checks:

1. mount reports bad superblock before the repair
2. xfs_repair output ends with done
3. After repair, cat /mnt/x/a.txt prints hello
4. xfs_repair -n "$L" prints No modify flag set (clean)

FAQ

常见问题

Why does xfs_repair refuse while the filesystem is mounted?

Repair changes metadata while the mounted kernel still holds cached state and journal assumptions, which produces an inconsistent result. Unmount first, or repair a snapshot on another host.

What is the difference between xfs_repair -n and plain xfs_repair?

-n scans and reports only; without it the tool writes changes. In production, dry-run and archive the output before deciding to repair.

Should I care about the stripe unit note?

If the volume sat on RAID with stripe geometry, verify and correct it with mount -o sunit=,swidth= as the message suggests; plain disks without RAID can ignore it.

Next steps

• Growing storage: LVM growth and XFS
• NFS mounts: NFS export and mount
• Post-install checks: 7 checks after install