About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.
The XFS driver logs "Metadata corruption detected at ..." (or "Metadata CRC error detected at ...") followed by "Unmount and run xfs_repair" when it reads a structure that fails its checks. The filesystem can shut itself down after that. The safe order is: stop writing, copy the disk, unmount, run xfs_repair -n to see what it would change, and only then repair. If xfs_repair reports a dirty log, mount and unmount the filesystem to replay it. Use -L, which destroys the log, only as a last resort.
The kernel's own text says what to do, but it does not say what each step costs. Each step that changes something carries its cost.
What the message means
The kernel source shows the wording. In xfs_error.c (tag v6.12) the XFS driver prints, for a failed metadata buffer, "Metadata corruption detected at %pS, %s block 0x%llx", where the first value is the code location and the second is the name of the checker for that kind of block. A variant says "Metadata CRC error detected" when the stored checksum does not match. For an inode it prints "Metadata %s detected at %pS, inode 0x%llx %s", where the first word is "corruption" or "CRC error". Each is followed by a second line, "Unmount and run xfs_repair". A different helper prints "Corruption detected. Unmount and run xfs_repair".
If the damage is serious, the filesystem is shut down. In xfs_fsops.c the shutdown line reads "%s (0x%x) detected at %pS (%s:%d). Shutting down filesystem.", where the first word is one of "Log I/O Error", "Corruption of in-memory data", "Corruption of on-disk metadata", "Block device removal" or "Metadata I/O Error". It is followed by "Please unmount the filesystem and rectify the problem(s)".
The line says "corruption", but the cause is not always the filesystem itself. A failing disk, a storage problem under a virtual machine, or a bad copy or restore can all produce it. The kernel message does not say which.
What fsck does for XFS
The fsck.xfs manual says: "XFS is a journaling filesystem and performs recovery at mount(8) time if necessary, so fsck.xfs simply exits with a zero exit status." It points to xfs_repair(8) for checks and repairs. A boot that passes through fsck.xfs therefore does not repair XFS. The manual adds that an administrator can force xfs_repair at boot with a /forcefsck file or fsck.mode=force on the kernel command line. Do not do that before you have a copy and know whether the log is dirty.
Likely causes
| Cause | What you see | How to confirm |
|---|---|---|
| Storage or disk fault | I/O errors in the kernel log around the same time; other filesystems on the disk also complain | dmesg or journalctl -k before the XFS line; disk, RAID and datastore health |
| Unclean shutdown with a dirty log | Message after a crash or power loss; xfs_repair stops with a dirty-log error |
xfs_repair -n prints the "ALERT" about valuable metadata changes in a log |
| Damage written by a bad copy, clone or restore | Fault appears right after a restore or snapshot revert | History of the disk; a mismatch between source and copy |
| Memory or controller fault | Corruption in different places, repeated after repairs | Hardware logs; repeat of the fault after a clean repair |
| A duplicate UUID blocks the mount (not corruption) | Mount fails after cloning a disk | See "XFS 'Filesystem has duplicate UUID ... can't mount' on a snapshot or restored disk" |
Prove the cause before changing anything
- Read the kernel log from before the first XFS line. The dmesg manual says
dmesgprints the kernel ring buffer, and the journalctl manual says-kshows only kernel messages:
journalctl -k
Look for errors from the disk driver, the storage controller, or the virtual disk before the XFS message. Those point below the filesystem.
Stop writes. Stop the service that uses the filesystem, then unmount it. The xfs_repair manual says the filesystem "must be unmounted, otherwise, the resulting filesystem may be inconsistent or corrupt".
Disruptive step: stopping the service takes it down, and unmounting makes the data on that filesystem unavailable to everything that uses it. To back out, mount the filesystem again (the mount command form is given under "Dirty log") and start the service. A filesystem that has already shut itself down may refuse a clean unmount; if it does, do not force it. Stop here and keep the copy in step 3.
Copy the disk before any repair. See "A failing disk in a Linux server: image it before you repair it". On a virtual machine, take a copy of the virtual disk at the hypervisor with the VM stopped.
Disruptive step: stopping the VM powers it off, so every service on it is down until you start it again. The copy reads the disk and does not change it. To back out, power the VM on. If you must read files out first, the kernel documentation says
norecoverymounts without running log recovery and the mount must be read-only. It warns the filesystem "is likely to be inconsistent" and "some files or directories may not be accessible".Run the repair tool in no-modify mode. The manual says
-n"should not modify the filesystem but should only scan the filesystem and indicate what repairs would have been made":
xfs_repair -n /dev/sdb1
Use your own device. The manual's exit status section says -n returns 1 if corruption was detected and 0 if none was. It also cautions that no-modify mode "is not completely accurate", because it "does not catch inconsistencies in the freespace and inode maps". A clean -n run is therefore good news, not a guarantee.
- If
-nprints an "ALERT" saying the filesystem "has valuable metadata changes in a log which is being ignored because the -n option was used", the log is dirty. The tool continues to say "Expect spurious inconsistencies which may be resolved by first mounting the filesystem to replay the log."
Example (illustrative): file01 logs "Metadata corruption detected at" a code location and a block number, then "Unmount and run xfs_repair" and later "Shutting down filesystem". The previous 20 minutes of journalctl -k show no disk errors, but the VM was powered off by the host five minutes earlier. The administrator stops the service, unmounts /dev/sdb1, stops the VM and copies the virtual disk. A normal /etc/fstab entry would mount the filesystem again at boot, which replays the log and changes what -n finds, so the administrator starts the VM with the /dev/sdb1 entry set to noauto (or boots to rescue mode), checks that /dev/sdb1 is not mounted, and runs xfs_repair -n /dev/sdb1. It prints the ALERT about the log being ignored. That is a dirty log, so the next step is to mount and unmount, not to repair.
Fix
Dirty log: replay by mounting, then unmount
The DIRTY LOGS section of the xfs_repair manual says "a dirty log can only be replayed by the kernel, on a machine having the same CPU architecture as the machine which was writing to the log", and that xfs_repair "cannot replay a dirty log and will exit with a status code of 2 when it detects a dirty log". The fix is "mounting and immediately unmounting the filesystem on the same class of machine that crashed". The manual adds: "make sure that the machine's hardware is reliable before replaying to avoid compounding the problems."
The xfs_repair message itself says the same, including a hint for snapshots: "If the filesystem is a snapshot of a mounted filesystem, you may need to give mount the nouuid option."
Disruptive step: mounting replays the log and writes to the disk. The xfs_repair manual names replay by mounting as the way to deal with a dirty log, but keep the copy you made. There is no way back after the log has been replayed, apart from restoring the copy. The mount command form is mount [-fnrsvw] [-o options] [-t fstype] device mountpoint and the unmount form is umount {directory|device}:
sudo mount -t xfs /dev/sdb1 /mnt/data
sudo umount /mnt/data
Use your own device and an empty mount point. For a snapshot or a restored copy, add the option the xfs_repair message names: -o nouuid (the kernel documentation says it skips the check for a double-mounted filesystem by UUID). Do not add norecovery here, because it skips the log replay that you want.
Repair
If the log is clean (or has just been replayed) and -n shows damage: after a replay, run xfs_repair -n /dev/sdb1 again and decide on that new result, because the earlier -n report was made with the log ignored (the ALERT text says to expect spurious inconsistencies).
Disruptive step: xfs_repair changes the filesystem.
xfs_repair /dev/sdb1
What the manual says it does: it fixes inconsistencies in inodes, directories, link counts and superblocks, and "orphaned files and directories (allocated, in-use but unreferenced) are reconnected by placing them in the lost+found directory", named by inode number. Where an inode claims blocks used by something else, "any inode that claims blocks used by the filesystem is deleted", and if two inodes claim the same block "they are both deleted". Quota information may be cleared, and the manual recommends checking quota limits afterwards. Back out only by restoring your copy.
Last resort: -L
The manual says -L "forces xfs_repair to zero the log even if it is dirty (contains metadata changes). When using this option the filesystem will likely appear to be corrupt, and can cause the loss of user files and/or data." In the DIRTY LOGS text: "All metadata updates in progress at the time of the crash will be lost, which may cause significant filesystem damage. This should only be used as a last resort." The xfs_repair message says to try a mount first.
Disruptive step: xfs_repair -L /dev/sdb1 destroys the log. The lost metadata updates cannot be recovered afterwards, and the only way back is your copy. Use it only if the mount fails and you have the copy.
Disk errors during repair
The manual says xfs_repair "aborts on most disk I/O errors", and that all blocks must be readable and writable first, "a possible method is using dd(8) to copy the data onto a good disk". That is another reason to image first.
Keep a metadata-only copy for support
The xfs_metadump manual describes copying a filesystem's metadata to a file, with most names obfuscated and "no data" copied. It is a debugging aid for XFS maintainers (the xfs_repair manual suggests it for filesystems that cannot be repaired). It is not a backup. The xfs_metadump manual also says it "cannot obfuscate metadata in the filesystem log", so a dump taken from a filesystem with a dirty log can carry clear-text names; read that part of the manual before sending a dump to anyone.
Confirm the fix
- Run
xfs_repair -n /dev/sdb1again. The manual says a clean filesystem returns 0. - Mount the filesystem and check
journalctl -kfor new XFS messages. Disruptive step: mounting writes to the disk and replays a dirty log if there is one. To back out, unmount it; a replayed log cannot be undone, so keep the copy you made. - Compare file counts and check the application's own consistency tools.
- Look in
lost+foundfor reconnected items named by inode number, and decide what they are.
What to watch afterwards
- A repeat of the message within weeks can point below the filesystem: disk, controller, memory or the hypervisor's storage.
- Watch for XFS lines in the kernel log, including "Metadata CRC error".
- Keep a tested backup that does not depend on the damaged volume.
- Check quotas, if used, after any repair.
Read next
Related articles you may want next.
- TroubleshootingA Linux Filesystem Became Read-Only: Preserve the First ErrorSeparate a policy read-only mount from an error response and preserve the evidence needed for safe offline repair decisions.Read article
- Backup & RecoveryXFS 'Filesystem has duplicate UUID ... can't mount' on a snapshot or restored diskA snapshot or restored XFS disk will not mount beside its original. Use nouuid for a safe look, or xfs_admin to give the copy a new UUID. Risks explained.Read article
- Backup & RecoveryA failing disk in a Linux server: image it before you repair itWhy a failing Linux disk should be imaged before repair: SMART evidence, ddrescue and its mapfile, read-only checks, and repairing the copy, not the original.Read article
Risks and limits
- These commands have not been run or lab-tested. They come from the manual pages, kernel documentation and source cited in Sources.
- Message text depends on kernel and xfsprogs versions. The text above is from kernel v6.12 files and the xfsprogs tree named in the version scope.
xfs_repaircan delete inodes and lose directory entries. The manual says so. A copy is the only reliable way to undo it.- The no-modify mode is documented as not completely accurate.
- A dirty log recorded on one CPU architecture cannot be replayed on another.
- This does not cover XFS on RAID or LVM layers beyond the filesystem itself, or realtime or external-log XFS setups (the manual's
-land-roptions).
Sources
- Linux kernel source: fs/xfs/xfs_error.c (v6.12) — Linux kernel project, tag v6.12, no date shown, accessed 18 November 2026
- Linux kernel source: fs/xfs/xfs_fsops.c (master) — Linux kernel project, master branch, no date shown, accessed 18 November 2026
- xfsprogs: repair/phase2.c — Ubuntu packaging tree, devel branch, no date shown, accessed 18 November 2026
- xfs_repair(8) — xfsprogs project, snapshot 2026-08-04, accessed 18 November 2026
- fsck.xfs(8) — xfsprogs project, snapshot 2026-08-04, accessed 18 November 2026
- mount(8) — util-linux project, snapshot 2026-08-03, accessed 18 November 2026
- umount(8) — util-linux project, snapshot 2026-08-03, accessed 18 November 2026
- xfs_metadump(8) — xfsprogs project, snapshot 2026-08-04, accessed 18 November 2026
- The SGI XFS Filesystem — Linux kernel documentation, no date shown, accessed 18 November 2026
- dmesg(1) — util-linux project, snapshot 2026-08-04, accessed 18 November 2026
- journalctl(1) — systemd project, systemd 262, no date shown, accessed 18 November 2026
This article was originally published on .