Filesystem Repair

Filesystem repair rewrites metadata to restore internal consistency. It can discard damaged references or data and can worsen loss when storage hardware is failing. Treat repair as a recovery operation: preserve evidence and recoverable data first, then use the tool documented for the exact filesystem.

Diagnose Before Repairing

Symptoms such as I/O errors, read-only remounts, missing files, or mount failures do not all prove filesystem corruption. First gather read-only evidence:

$ findmnt --target /affected/path
$ lsblk -f
$ journalctl -k -b

Check the storage stack, device health, cables or network path, RAID state, encryption, and recent events. If the device is failing, repeated scans can consume its remaining life. Capture an image or clone with a recovery-oriented tool and work on the copy when feasible.

Identify the Exact Filesystem and Device

Determine whether the filesystem lives on a partition, logical volume, RAID device, encrypted mapping, or whole disk. Do not run a checker against /dev/sda merely because a child partition such as /dev/sda1 is affected.

Use lsblk -f, blkid, findmnt, and storage-layer tools to map the target. Detection signatures can be stale, so reconcile them with known configuration and backups.

Make the Filesystem Offline

Most traditional consistency checkers require the filesystem to be unmounted. A mounted filesystem changes while the checker reads it, and repair writes can conflict with the kernel's cached state, causing corruption.

Stop dependent services, unmount nested filesystems, move process working directories, and deactivate higher layers as required. For the root filesystem, boot a rescue environment or use the distribution's documented offline check mechanism. Confirm with findmnt that the target is not mounted in the relevant namespace.

Use the Filesystem-Specific Tool

fsck is a front end that can invoke filesystem-specific helpers. It is not one universal repair engine. Examples of distinct workflows include e2fsck for ext filesystems, xfs_repair for XFS, and filesystem-specific Btrfs diagnostic and recovery tools.

Options with similar names can have different semantics. In particular, do not apply --repair or force flags copied from another filesystem's guide. Read the installed manual and current project or distribution recovery documentation. Begin with a no-modification or diagnostic mode if that implementation provides a reliable one, capture output, and understand the proposed fixes.

Verify and Restore Service

Record the repair tool, version, options, output, and exit status. After repair, repeat device-health checks, mount read-only first where appropriate, inspect critical data, and compare with known backups. Then restore normal mounts and services gradually while monitoring kernel and application logs.

A filesystem becoming mountable does not prove every file is correct. Restore lost or damaged application data from backups and validate at the application layer.

Summary

You can now plan filesystem repair as a staged recovery procedure.

1. Diagnose hardware and preserve recoverable data before writes.
2. Map the exact filesystem-containing block layer.
3. Make the filesystem offline in the relevant namespace.
4. Use the documented filesystem-specific diagnostic and repair tool.
5. Validate device health, filesystem state, and application data separately.