Check an ext4 File System Safely with e2fsck

You will finish with a read-only file system check, a way to interpret its exit status, and a clear decision about when repair is safe. The 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 can take much longer.

This guide covers ext2, ext3 and ext4 file systems. The commands named 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. You need elevated privileges to inspect most real devices, but not necessarily to check an image that you own.

1. Identify the target before touching it

First confirm which device or image contains the file system. A wrong device is the most expensive possible typo here. Replace /dev/DEVICE with a path you have verified, and do not copy that placeholder literally.

$ 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 says that checking a mounted file system is generally unsafe and that even a read-only result is not valid as a file system check while it is mounted.

2. Run the non-destructive check first

Use -n for a non-interactive, read-only check. It answers no to repair questions 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-file-system check. The manual gives a narrow exception for -n without those options, but the printed results are still not a valid check while mounted. For a trustworthy result, run the command after the file system is unmounted.

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. A clean result is not a reason to run a repair anyway. Avoid -f unless you specifically need a full check: it forces checking even when the file system is marked clean and can add 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 present.

$ 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

Status 0 means no errors were found. Status 1 means file system errors were corrected, although -n itself does not make repairs, so this value is more commonly seen after a repair run. Status 2 means errors were corrected and a reboot is recommended. Status 4 means errors remain uncorrected. Status 8 is an operational error, 16 is a usage or syntax error, 32 means the run was cancelled, and 128 indicates a shared-library error. The values are added together, so do not assume that every non-zero status has only one meaning.

4. Repair only while the file system is offline

Repair changes metadata and can affect recoverability. Make sure you have a current backup or image, identify 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 that e2fsck considers safe to repair without intervention. If it finds a problem needing an administrator's decision, it reports the problem and includes status 4. This is the mode commonly used by boot scripts.

Interactive mode is the default when none of -n, -p or -y is used. It asks about each problem. -y answers yes to every question and can make broad changes, so reserve it for a deliberate recovery procedure with a backup and a record of why it is appropriate. Never combine -n with -p or -y; e2fsck rejects those combinations.

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

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

Mount only after the second check gives you a result you understand. If status 2 was returned, follow the stated reboot requirement. If status 4 remains, keep the file system offline and investigate rather than repeatedly forcing repairs.

5. Use recovery options only with matching evidence

Do not start with a guessed 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 such as sparse superblocks. Use mke2fs -n with arguments that match the existing layout to determine candidate locations, then verify the result with a specialist recovery procedure.

For a bad-block scan, -c asks e2fsck to run a read-only badblocks scan and add any findings to the bad-block inode. Using -c twice requests a non-destructive read-write test. That is a device-stressing operation, not a harmless diagnostic, so obtain storage approval and a backup first.

The -z UNDO_FILE option records old block contents in an undo file before overwriting them. It can support recovery with e2undo, but the manpage warns that an undo file cannot recover from a power failure or system crash. 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, which is useful for testing a separate configuration without editing 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

The example enables extra reporting and sets the default undo-file directory. Check that the directory exists and has suitable permissions before relying on it. Avoid editing the [problems] stanza casually: its problem-code settings can change repair decisions and the manual warns that inappropriate values may make e2fsck behave incorrectly or crash. A logging setup belongs in a separate change with a tested fallback directory, especially during early boot.