Alibaba Cloud Linux:What do I do when the "Structure needs cleaning" error message appears for an Ext4 file system?

Problem description

After you mount a disk device, the "Structure needs cleaning" error message appears when files are read from the Ext4 file system on the device.

Cause

In most cases, the preceding issue occurs because the metadata of the Ext4 file system on the disk device is corrupted. In this case, you must repair the Ext4 file system to resolve the issue.

Solution

1. Unmount the problematic Ext4 file system.

Unmount the corresponding disk device. In this example, the /dev/vdd1 partition is used. Run the df -Th command to view information about all mount points. The following command output is returned:

Filesystem     Type      Size  Used Avail Use% Mounted on
devtmpfs       devtmpfs   16G     0   16G   0% /dev
tmpfs          tmpfs      16G     0   16G   0% /dev/shm
tmpfs          tmpfs      16G  552K   16G   1% /run
/dev/vda3      ext4       99G   15G   80G  16% /
tmpfs          tmpfs      16G  4.0K   16G   1% /tmp
/dev/vda2      vfat      200M  5.8M  195M   3% /boot/efi
tmpfs          tmpfs     3.1G     0  3.1G   0% /run/user/0
/dev/vdd1      ext4       98G   24K   93G   1% /mnt

The preceding command output indicates that the /dev/vdd1 partition is mounted to /mnt. Run the following command to unmount the /dev/vdd1 partition from /mnt:

 sudo umount /mnt

Run the df -Th command to check whether the /dev/vdd1 partition is unmounted:

Filesystem     Type      Size  Used Avail Use% Mounted on
devtmpfs       devtmpfs   16G     0   16G   0% /dev
tmpfs          tmpfs      16G     0   16G   0% /dev/shm
tmpfs          tmpfs      16G  552K   16G   1% /run
/dev/vda3      ext4       99G   15G   80G  16% /
tmpfs          tmpfs      16G  4.0K   16G   1% /tmp
/dev/vda2      vfat      200M  5.8M  195M   3% /boot/efi
tmpfs          tmpfs     3.1G     0  3.1G   0% /run/user/0

2. Check the status of the Ext4 file system on the disk device.

You can run the dumpe2fs command to check the status of the Ext4 file system on the disk device. Before you run the dumpe2fs command, run the following command to check whether dumpe2fs is installed:

dumpe2fs -V

If the version number of dumpe2fs is displayed in the command output, dumpe2fs is installed. Otherwise, run the following command to install the e2fsprogs package:

sudo yum -y install e2fsprogs

Run the dumpe2fs command to check the status of the Ext4 file system on the disk device. In this example, the /dev/vdd1 partition is used.

 sudo dumpe2fs /dev/vdd1 

The following command output is returned:

Filesystem volume name:   <none>
......
Filesystem state:         clean with errors
Errors behavior:          Continue
Filesystem OS type:       Linux
......
FS Error count:           9
First error time:         Thu Dec 26 12:58:52 2024
First error function:     ext4_ext_check_inode
First error line #:       520
First error inode #:      13
First error err:          EFSCORRUPTED
Last error time:          Thu Dec 26 15:35:37 2024
Last error function:      ext4_ext_check_inode
Last error line #:        520
Last error inode #:       13
Last error err:           EFSCORRUPTED
Journal features:         journal_64bit
Total journal size:       256M
Total journal blocks:     65536
Max transaction length:   65536
Fast commit length:       0

Filesystem state: clean with errors in the preceding command output indicates that errors occurred in the Ext4 file system. First error function: ext4_ext_check_inode in the command output indicates that the first error occurred in the ext4_ext_check_inode() kernel function.

3. Repair the Ext4 file system.

fsck.ext4 is a tool in Linux used for checking and repairing Ext4 file systems. fsck.ext4 checks the integrity of Ext4 file systems and identifies and fixes errors in the file systems. fsck.ext4 can identify different types of errors, including the following errors:

• Lost data blocks: For example, an inode is marked as in use, but the corresponding data block does not exist.

• Multiply-allocated data blocks: The same data block is allocated to multiple inodes.

• Lost or damaged superblocks: The superblock of the file system may be damaged.

When fsck.ext4 identifies an error, fsck.ext4 attempts to fix the error. The fix operations may include the following operations:

• Restore superblock information and create new superblock copies.

• Release unused or multiply allocated data blocks.

• Update inode status information to ensure that inodes match the actual usage of data blocks.

• Repair file system links, such as incorrect directory entries.

Run the following command to repair the Ext4 file system on the disk device. In this example, the /dev/vdd1 partition is used.

sudo fsck.ext4 /dev/vdd1 

The preceding fsck.ext4 command checks the partition for errors and asks whether to fix the identified errors.

Pass 1: Checking inodes, blocks, and sizes
Inode 13 has corrupt extent header.  Clear inode<y>?  yes
Inode 13, i_blocks is 8, should be 0.  Fix<y>?  yes
Pass 2: Checking directory structure
Entry 'testfile.txt' in / (2) has deleted/unused inode 13.  Clear<y>?  yes
Pass 3: Checking directory connectivity
Pass 4: Checking reference counts
Pass 5: Checking group summary information
Block bitmap differences:  -34816
Fix<y>?  yes
Free blocks count wrong for group #1 (31735, counted=31736).
Fix<y>?  yes
Free blocks count wrong (12822641, counted=12822642).
Fix<y>?  yes
Inode bitmap differences:  -13
Fix<y>?  yes
Free inodes count wrong for group #0 (8180, counted=8181).
Fix<y>?  yes
Free inodes count wrong (3276788, counted=3276789).
Fix<y>?  yes

/dev/vdd1: ***** FILE SYSTEM WAS MODIFIED *****
/dev/vdd1: 11/3276800 files (0.0% non-contiguous), 284558/13107200 blocks

Enter y for each error to fix the error or run the following command to fix all errors:

fsck.ext4 -y /dev/vdd1 

Run the dumpe2fs command to check the status of the Ext4 file system on the disk device. In the command output, the value of the Filesystem state parameter is clean, instead of clean with errors.

...
Filesystem state:         clean
...