Using xfs_repair to Fix Corrupted Linux XFS Volumes

The xfs_repair utility is a dedicated maintenance tool used in Linux to detect and resolve filesystem inconsistencies, structural damage, and corruption within XFS partitions. This article covers the specific role of xfs_repair, how it functions during recovery operations, the critical rules for running it safely, and common command options used to restore damaged XFS storage volumes to a healthy, mountable state.

The Purpose of xfs_repair

XFS is a high-performance, 64-bit journaling filesystem designed for scalability. Unlike traditional filesystems like ext4 that utilize generic fsck wrappers for filesystem repairs, XFS uses xfs_repair as its native, specialized recovery utility.

The primary objective of xfs_repair is to guarantee filesystem consistency. When unexpected shutdowns, power failures, or storage hardware malfunctions disrupt write operations, metadata can become out of sync or damaged. The xfs_repair utility analyzes the metadata structures—such as allocation groups, inodes, directories, and B-trees—and repairs or discards invalid structures so the operating system can safely mount and access the volume again.

How xfs_repair Operates

The repair process works in distinct phases:

  1. Superblock and Geometry Verification: Checks the primary and backup superblocks to determine the filesystem layout and geometry.
  2. Log Verification: Examines the internal or external journaling log. Under normal circumstances, an XFS volume should be mounted and unmounted so the kernel can replay pending log transactions. If the log is damaged or unreadable, xfs_repair can clear it.
  3. Allocation Group Scanning: Validates free space B-trees, inode maps, and reference counters within each allocation group.
  4. Inode Inspection: Traverses all inodes to confirm file attributes, pointers, and data block maps. Any pointers to invalid blocks are pruned.
  5. Directory Tree Rebuilding: Confirms the integrity of the directory hierarchy. Disconnected or orphaned files are moved to the lost+found directory.

Essential Rules for Running xfs_repair

To prevent catastrophic data loss, xfs_repair must never be run on an actively mounted filesystem. Modifying metadata blocks while the kernel actively reads or writes to them will lead to further data corruption.

Before running the utility, unmount the target partition:

umount /dev/sdX1

If the root filesystem is corrupted, you must boot into a recovery environment, rescue image, or single-user mode to ensure the root volume remains unmounted or mounted read-only before performing maintenance.

Common Usage Examples

Dry-Run / Inspection Mode To inspect a filesystem for damage without making any changes to the disk, use the -n (no modify) flag:

xfs_repair -n /dev/sdX1

This command outputs detected errors and reports what actions would be taken, making it safe for diagnostic evaluation.

Standard Repair To repair an unmounted volume and resolve all detected issues:

xfs_repair /dev/sdX1

Zeroing the Log (Last Resort) If the filesystem journal cannot be replayed due to severe corruption, xfs_repair will halt and refuse to continue without the -L (zero log) flag. Zeroing the log clears pending journal transactions, which may cause the loss of the most recent writes, but allows the utility to proceed with repairing the remaining structure:

xfs_repair -L /dev/sdX1

This option should only be used when normal repair attempts fail and the log cannot be recovered by mounting.