Linux · critical · Storage, filesystems & NFS

XFS: "Structure needs cleaning" or a filesystem that will not mount

XFS has found metadata it does not trust and has shut the filesystem down rather than write more into it.

What you see

The filesystem goes read-only or unmounts itself, and the kernel log carries a metadata corruption message. A mount attempt fails with structure needs cleaning.

What is actually wrong

Almost always the storage underneath — a failing disk, a controller that lost cache on a power failure, or a SAN path that dropped. XFS itself is not the fault; it is the layer that noticed.

Codes and articles

Structure needs cleaningXFS_WANT_CORRUPTED_GOTOxfs_repairMetadata corruption detectedEFSCORRUPTED

Fixes (2)

Check the hardware and take an image before repairing

Root shell1–4 hourslow riskreversible

No backup, or the data matters. xfs_repair can discard what it cannot reconcile.

Read the kernel log for what actually happened. I/O errors underneath change the whole approach.
Shell
```
dmesg -T | grep -iE 'xfs|i/o error|medium error|reset' | tail -40
```
Repairing a filesystem on a disk that is still failing produces a filesystem that fails again in an hour, having lost whatever the repair discarded. The hardware question comes first.

Check the drive's own health.

Shell

sudo smartctl -a /dev/sda | grep -iE 'result|reallocated|pending|uncorrectable|error'

Unmount it. Do not repair a mounted filesystem.
Shell
```
sudo umount /data || sudo umount -l /data
```
Take a metadata dump, which is small and lets the repair be tested elsewhere.
Shell
```
sudo xfs_metadump /dev/sdb1 /root/data-metadump.img
```
Where the data matters and there is somewhere to put it, take a full image with a tool that reads past errors.
Shell
```
sudo ddrescue -f -n /dev/sdb1 /mnt/rescue/sdb1.img /mnt/rescue/sdb1.log
```

Confirm it workedYou have an image or a metadump, and a clear answer on whether the disk is failing.

If you need to undo itNothing was changed on the filesystem.

Replay the log, then repair

Root shell, filesystem unmounted30–90 minuteshigh risknot reversible

After the checks above. Order matters here more than anywhere.

Try mounting first. A dirty log replays on mount, and that alone resolves many of these.
Shell
```
sudo mount /dev/sdb1 /data
```
xfs_repair with -L destroys the log, and the log holds the most recent metadata changes. Mounting to replay it cleanly first is the difference between losing nothing and losing the last few minutes of writes.
If it mounts, unmount cleanly and then run a check.
Shell
```
sudo umount /datasudo xfs_repair -n /dev/sdb1
```
The -n flag reports without changing anything. Read the output before running it for real.
Run the repair.
Shell
```
sudo xfs_repair /dev/sdb1
```
Only if it refuses because the log is dirty and cannot be replayed, use -L. This discards the log and loses the transactions in it.
Shell
```
sudo xfs_repair -L /dev/sdb1
```
-L is the option every search result offers first. It is a last resort, it is not reversible, and it should follow a failed mount rather than replace it.

Mount and check what landed in lost+found.

Shell

sudo mount /dev/sdb1 /datals -la /data/lost+found | head -20

Confirm it workedThe filesystem mounts, xfs_repair -n is clean, and the application's data is present and correct.

Shell

sudo umount /data && sudo xfs_repair -n /dev/sdb1 && sudo mount /dev/sdb1 /data

If you need to undo itRestore the image taken beforehand. Without it there is no way back.

Related faults

Where this stops. This write-up was written and checked by hand. It says what each step changes, how to confirm it worked and how to reverse it, and anything destructive is flagged before you reach it. If it does not match what your machine is doing, search the Support Centre for the exact code or message — and when something needs a person, get in touch.