Check and Repair an ext4 File System with e2fsck

A dirty ext4 file system can strand a boot at the worst possible moment, and e2fsck is the tool you reach for to work out how bad it actually is. This walks through a read-only check, how to read the exit status, and when repair is actually safe. Examples use e2fsprogs 1.47.0, installed here as package version 1.47.0-2.4~exp1ubuntu4.1. Allow 10 minutes for a check on a small image; a real disk takes much longer.

This guide covers ext2, ext3 and ext4 file systems: the commands fsck.ext2, fsck.ext3 and fsck.ext4 are aliases of the same installed e2fsck implementation. You need a shell and the path to the block device or file containing the file system, and elevated privileges to inspect most real devices, though not necessarily to check an image you own.

1. Find the target before you touch anything

Identify the device or image first. A wrong device is the most expensive typo in this whole guide. Replace /dev/DEVICE with a path you have actually verified, never the placeholder itself.

$ lsblk -f
$ findmnt -S /dev/DEVICE

lsblk -f shows file system types, labels and mount points. findmnt tells you whether the exact source is mounted. If it is mounted, stop before running a repair: e2fsck itself says checking a mounted file system is generally unsafe, and that even a read-only result there is not a valid check.

2. Run the non-destructive check first

Use -n for a non-interactive, read-only check. It answers no to every repair question and opens the file system read-only. This is the normal first pass when you are investigating a warning or planning maintenance.

$ sudo e2fsck -n /dev/DEVICE

• Do not add -c, -l or -L to a mounted check. The manual gives a narrow exception for -n alone, but the printed results still are not a valid check while mounted.
• Run for a trustworthy result only after unmounting. A clean pass while mounted proves nothing certain.

On a clean ext4 image, the installed command prints five checking passes and ends with a line similar to this:

e2fsck 1.47.0 (5-Feb-2023)
Pass 1: Checking inodes, blocks, and sizes
Pass 2: Checking directory structure
Pass 3: Checking directory connectivity
Pass 4: Checking reference counts
Pass 5: Checking group summary information
/path/to/image: 11/8192 files, 1549/8192 blocks

The counts and fragmentation percentage vary by file system. A clean result is not a reason to run a repair anyway. Skip -f unless you specifically need a full check: it forces checking even on a file system marked clean and adds unnecessary work.

3. Read the exit status as a result, not a failure flag

Capture the status immediately after e2fsck exits. Its status is a bit mask, so more than one condition can be true at once.

$ sudo e2fsck -n /dev/DEVICE
$ status=$?
$ printf 'e2fsck exit status: %s\n' "$status"
$ case "$status" in
> 0) printf '%s\n' 'No errors' ;;
1) printf '%s\n' 'Errors were corrected' ;;
2) printf '%s\n' 'Errors were corrected; reboot is recommended' ;;
4) printf '%s\n' 'Errors remain uncorrected' ;;
*) printf '%s\n' 'Inspect the bit mask and command output' ;;
esac

• 0 means clean. No errors were found.
• 1 means corrected. File system errors were fixed, although -n itself never makes repairs, so this value normally follows a repair run instead.
• 2 means corrected, reboot needed. Follow that instruction before mounting again.
• 4 means still broken. Errors remain uncorrected.
• 8, 16, 32 and 128 are operational codes. Operational error, usage or syntax error, cancelled run, and shared-library error respectively. Values add together, so never assume a non-zero status has only one meaning.

4. Repair only while the file system is offline

Repair changes metadata and can affect recoverability. Have a current backup or image, pick a maintenance window, and unmount the target before choosing an automatic repair mode.

$ sudo umount /mount/point
$ sudo e2fsck -p /dev/DEVICE

-p, also called preen mode, fixes problems e2fsck considers safe to repair without asking. If it finds a problem needing a human decision, it reports the problem and includes status 4: this is the mode boot scripts commonly use.

Interactive mode is the default when none of -n, -p or -y is given, and it asks about each problem in turn. -y answers yes to everything and can make broad changes, so keep it for a deliberate recovery procedure with a backup and a written reason. Never combine -n with -p or -y; e2fsck rejects those combinations outright.

After a repair, run the offline read-only check again before trusting the result:

$ sudo e2fsck -n /dev/DEVICE
$ sudo mount /dev/DEVICE /mount/point

Mount only once that second check gives you a result you understand. If status 2 came back, follow the stated reboot requirement. If status 4 remains, keep the file system offline and investigate instead of repeatedly forcing repairs.

5. Use recovery options only with matching evidence

• Never guess a backup superblock. If the primary superblock is damaged, e2fsck can use -b BACKUP_SUPERBLOCK, but the correct location depends on block size, blocks per group and features like sparse superblocks. Run mke2fs -n with arguments matching the existing layout to find candidate locations, then verify with a specialist recovery procedure.
• Treat a bad-block scan as a real operation, not a quick diagnostic. -c asks e2fsck to run a read-only badblocks scan and add findings to the bad-block inode; using it twice requests a non-destructive read-write test, which stresses the device. Get storage approval and a backup first.
• Know what -z UNDO_FILE does and does not do. It records old block contents in an undo file before overwriting them, which can support recovery with e2undo. The manpage warns it cannot recover from a power failure or system crash, so it is not a substitute for a backup.

6. Keep configuration changes narrow

The optional /etc/e2fsck.conf file uses INI-style stanzas. e2fsck also honours E2FSCK_CONFIG, handy for testing a separate configuration without touching the system file. Command-line options generally override defaults, so keep a one-off check explicit when its behaviour matters.

[options]
report_verbose = true
report_time = true

[defaults]
undo_dir = /var/lib/e2fsprogs/undo

This example enables extra reporting and sets the default undo-file directory. Check that the directory exists and has suitable permissions before relying on it. Leave the [problems] stanza alone unless you mean it: its problem-code settings change repair decisions, and the manual warns that inappropriate values may make e2fsck behave incorrectly or crash. Keep a logging change separate from anything touching early boot, with a tested fallback directory.