Fix "Structure needs cleaning" (XFS and ext4 Corruption)

sudo umount /dev/sdb1
# XFS
sudo xfs_repair /dev/sdb1
# ext4
sudo e2fsck -f /dev/sdb1

What the error means

"Structure needs cleaning" is how the C library prints EUCLEAN. A file system driver returns it when it reads metadata that fails validation, for example an inode with impossible values or a directory block with a bad checksum. Rather than risk spreading the damage, the driver refuses the operation. You see it from ordinary commands:

ls: cannot access 'photos/IMG_2041.jpg': Structure needs cleaning
rm: cannot remove 'cache/tmp123': Structure needs cleaning
mount: /data: mount(2) system call failed: Structure needs cleaning.

The kernel log has the detail. Check it before anything else:

sudo dmesg | grep -Ei 'xfs|ext4|btrfs' | tail -20

Example output on XFS and ext4:

XFS (sdb1): Metadata corruption detected at xfs_dinode_verify+0x1a0/0x7a0 [xfs], inode 0x2a0c4 dinode
XFS (sdb1): Corruption of in-memory data (0x8) detected at xfs_trans_cancel+0x15d/0x180 [xfs]. Shutting down filesystem.
EXT4-fs error (device sda2): ext4_lookup:1855: inode #393218: comm ls: deleted inode referenced: 393472

XFS is the file system you will most often see this with (it is the default on Fedora Server and RHEL-family systems), but ext4 and Btrfs return the same error.

Step 1: protect the data and check the hardware

Corruption is caused by something: an unclean power loss, a failing disk, bad RAM, a flaky cable or USB enclosure, or a kernel bug. Repairing on failing hardware can turn a few bad inodes into a lost file system.

sudo smartctl -a /dev/sdb | grep -Ei 'result|reallocated|pending|uncorrect|media'

Install smartmontools if smartctl is missing. If SMART reports failure, reallocated or pending sectors, or media errors, do not repair in place:

sudo ddrescue -n /dev/sdb1 /mnt/backup/sdb1.img /mnt/backup/sdb1.map

If the disk is healthy and the data matters, copy what you can still read (rsync or the rsync backup script) before repairing.

Step 2: unmount the file system

findmnt /dev/sdb1
sudo umount /dev/sdb1

If umount says the target is busy, stop the processes using it (sudo fuser -vm /data). XFS that has shut itself down can still be unmounted. For the root file system, or /home if you cannot log in without it, boot from a live USB or the distro's rescue mode; the disk then is not mounted and you can repair it from there. If the system dropped into emergency mode because of this, you can often repair a non-root file system right from that shell.

Step 3a: repair XFS

Do a dry run first. -n reports problems without changing anything:

sudo xfs_repair -n /dev/sdb1
sudo xfs_repair /dev/sdb1

If xfs_repair refuses with this message:

ERROR: The filesystem has valuable metadata changes in a log which needs to
be replayed.  Mount the filesystem to replay the log, and unmount it before
re-running xfs_repair.

do exactly what it says. Mounting replays the journal, which writes the pending changes safely:

sudo mount /dev/sdb1 /mnt
sudo umount /mnt
sudo xfs_repair /dev/sdb1

sudo xfs_repair -L /dev/sdb1

Afterwards mount it and look in lost+found at the top of the file system for recovered files, which are named by inode number.

Step 3b: repair ext4

sudo e2fsck -f /dev/sdb1          # interactive, asks before each fix
sudo e2fsck -f -y /dev/sdb1       # answers yes to everything

-f forces a full check even if the file system is marked clean. Interactive mode lets you see what it changes; -y is practical when there are hundreds of errors. Run it again until it reports no problems. If it cannot find the superblock, use a backup one as shown in wrong fs type, bad superblock.

For an ext4 root file system you can also ask systemd to repair it at the next boot, before it is mounted read-write: add fsck.mode=force fsck.repair=yes to the kernel command line once from the GRUB menu (press e). This does not work for XFS, whose fsck.xfs does nothing.

Step 3c: Btrfs

Btrfs reports corrupted metadata as "Structure needs cleaning" or "corrupt leaf" in dmesg. Its repair tool is risky, so the order is:

sudo btrfs scrub start -B /          # on a mounted fs, fixes from redundant copies if any
sudo btrfs check --readonly /dev/sdb1 # unmounted, reports only
sudo mount -o ro,rescue=usebackuproot /dev/sdb1 /mnt   # copy data off

Use btrfs check --repair only after copying data off, and ideally after asking on the Btrfs mailing list. Corrupt leaf messages on Btrfs very often point to bad RAM; test it.

Distro-specific notes

All the major distros' live images include these tools. On Fedora Server or RHEL-family systems with XFS root, the installer ISO's "Troubleshooting" boot entry gives you a shell where the root volume is not mounted.

How to prevent it

• Avoid hard power-offs; use a UPS for servers and always unmount or eject external drives.
• Enable SMART monitoring (smartd from smartmontools) so failing disks warn you early.
• Run monthly btrfs scrub on Btrfs; on XFS, xfs_scrub can check a mounted file system on current kernels.
• Keep backups and snapshots. Repairs restore consistency, not your data; see Timeshift and Snapper snapshots and the disk management guide.
• If the file system went read-only rather than throwing this error, see Read-only file system.

Frequently asked questions