Safely Check and Repair an XFS Filesystem with xfs_repair

You will finish with a read-only XFS consistency check, a controlled repair run if one is needed, and a clear interpretation of the result. The workflow keeps the filesystem unmounted and treats log erasure as a last resort.

These examples use xfs_repair 6.6.0 from Ubuntu package xfsprogs 6.6.0-1ubuntu2.1. Allow at least fifteen minutes for preparation and checking. A large or badly damaged filesystem can take much longer, and the repair itself may need substantial memory and uninterrupted maintenance time.

1. Identify the filesystem and command version

Do this as an ordinary user first. Replace /dev/DEVICE with the XFS block device, not its mount directory. Check the command that will actually run and record its version:

$ command -v xfs_repair
/usr/sbin/xfs_repair
$ xfs_repair -V
xfs_repair version 6.6.0
$ findmnt -t xfs
/dev/DEVICE on /srv/data type xfs (rw,relatime)

Your findmnt output will differ. If the device is mounted, stop here. Repairing a mounted filesystem can leave it inconsistent or corrupt. The normal workflow is to boot into maintenance or rescue mode, stop services that use the filesystem, and unmount it cleanly.

Checkpoint: write down the exact device path and its current mount point. Do not infer a device from a familiar-looking label or partition number.

2. Unmount it cleanly

This step needs elevated privileges because it changes system state. First find processes that still have files open, then stop the owning service through its normal service manager:

# findmnt /srv/data
# fuser -vm /srv/data
# systemctl stop YOUR-SERVICE.service
# umount /srv/data
# findmnt /srv/data

The final command should print nothing for that mount point. Do not use a forced or lazy unmount as a shortcut for understanding which service is still writing. If this is the root filesystem, use a supported rescue environment instead of trying to repair it from the running system.

After an unclean crash, a clean mount and unmount can allow the kernel to replay the XFS log. That matters because xfs_repair cannot replay a dirty log itself.

3. Run the no-modify check

# xfs_repair -n /dev/DEVICE

A clean check exits with status 0. A detected inconsistency exits with status 1. Capture the status immediately, because a later shell command replaces $?:

# xfs_repair -n /dev/DEVICE
# repair_status=$?
# printf 'xfs_repair -n exit status: %s\n' "$repair_status"
xfs_repair -n exit status: 0

In a damaged filesystem, messages describe the structures involved. For example, an orphaned inode may be reported as disconnected and later moved into lost+found. No-modify mode is a planning aid, not a perfect preview: the manual warns that it can miss some freespace and inode-map inconsistencies and can repeat warnings because it cannot fix problems as it scans.

Do not add -L to make this check pass. That flag is unrelated to a normal read-only assessment.

4. Repair only after the check and backup

If the no-modify run reports corruption, confirm the backup and maintenance window before proceeding. The modifying command is:

# xfs_repair /dev/DEVICE

Without -e, a modifying run returns 0 when it completes without a runtime problem, even if it corrected metadata. That makes the output and the filesystem state more useful than treating status 0 as proof that nothing changed. Use verbose output when the progress or diagnostics need more detail:

# xfs_repair -v /dev/DEVICE

After it finishes, read the complete output and check the status:

# repair_status=$?
# printf 'repair exit status: %s\n' "$repair_status"
repair exit status: 0

For scripts or a maintenance record, -e makes a repaired metadata problem return status 4. It cannot be combined with -n. A runtime failure returns 1 and the manual says to restart xfs_repair; status 2 means the tool stopped because it found a dirty log.

5. Handle a dirty log without erasing it

A dirty log normally means the filesystem was not cleanly unmounted. First use the same class of machine and CPU architecture that wrote the log, mount the filesystem, and unmount it immediately so the kernel can replay the log:

# mount /dev/DEVICE /mnt/xfs-recovery
# umount /mnt/xfs-recovery
# xfs_repair -n /dev/DEVICE

Mounting a damaged filesystem is a deliberate recovery action. Use a reliable host, keep the mount window short, and check that the mount and unmount both succeeded. If the mount cannot replay the log, preserve the evidence and investigate the underlying storage before escalating.

Last resort: xfs_repair -L /dev/DEVICE forcibly zeros the log. This discards metadata updates that were in progress at the crash and can cause significant file or data loss. It is not an alternative spelling of -n, and it is not a general fix for a failed repair. Use it only when the log cannot be replayed, you accept the loss, and you have a recovery plan.

6. Avoid misleading fixes and tune only with evidence

-f is for an XFS filesystem image stored in a regular file, not for an ordinary block device. It also tells the tool that any external log or realtime section is in a regular file. A safe image check has this shape:

# xfs_repair -n -f /path/to/xfs-image

For a filesystem with an external log or realtime section, supply the matching devices with -l LOGDEV and -r RTDEV. Do not guess these paths. Obtain them from the system's filesystem and storage records.

The default memory limit scales towards the lesser of the process virtual address limit and about 75 percent of physical RAM. If the repair is constrained, -m MAXMEM_MB sets an approximate maximum in megabytes, but the process may use more. A low limit can make a long repair slower, so change it only when you have a measured memory constraint and enough time.

If a run appears stuck, -P disables prefetching of inode and directory blocks. Interrupting a stuck run is safe according to the manual; do not kill it repeatedly just because progress is quiet. With parallel allocation-group processing enabled, -t SECONDS changes reporting intervals, but ordinary runs do not necessarily print periodic progress.

7. Mount and verify the repaired filesystem

When repair exits successfully, mount the filesystem in a controlled window and inspect the result. This changes state and may trigger quota accounting work:

# mount /dev/DEVICE /mnt/xfs-recovery
# findmnt -no SOURCE,FSTYPE,OPTIONS /mnt/xfs-recovery
/dev/DEVICE xfs rw,relatime
# ls -ld /mnt/xfs-recovery/lost+found
# journalctl -k -b --no-pager | tail -50

Look for the expected XFS type, accessible directories and kernel errors. If lost+found exists, inspect its inode-numbered entries and recover files by content and ownership rather than guessing from the name. Do not delete those entries until you have confirmed they are not needed.

If quotas are enabled, repair may clear quota information. Check quota limits manually after repair. Space usage is regenerated on a later quota-enabled mount, which may make that mount take longer.