To recover a BTRFS filesystem with checksum verify failed errors, you must immediately unmount the damaged volume to prevent further data corruption. Once isolated, use btrfs restore or btrfs rescue commands to extract readable files to a healthy storage location. This offline approach prioritizes data preservation over online repair mechanisms like scrubbing, which can fail on severely corrupted structures.
Immediate Stabilization Steps
When your system reports a checksum verify failed error, the integrity of the metadata or data blocks is compromised. The most critical action is to stop all write operations to the affected partition. If the drive is mounted as read-write, any new writes may overwrite recovering sectors or trigger kernel-level checks that exacerbate the issue. You should unmount the filesystem using the standard unmount command. For example, if your drive is mounted at/mnt/data, execute sudo umount /mnt/data. If the system reports that the device is busy, identify and terminate processes accessing the mount point using tools like fuser -vm /dev/sdX1 before attempting to unmount again.
It is essential to understand that online repair tools are not suitable for this specific failure mode during an active emergency. While btrfs scrub start is designed for background health checks and automatic repair of correctable errors, it requires the filesystem to be mounted and coherent. A checksum failure often indicates deeper structural issues that require offline analysis. Attempting to run a scrub on a failing disk can lead to I/O errors that halt the process entirely. Therefore, the strategy shifts from maintenance to forensic recovery.
Assessing the Damage Scope
Before attempting complex recovery procedures, determine the extent of the corruption. Check the system logs usingdmesg | grep btrfs to see detailed error messages. These logs will reveal whether the error is limited to a single file or affects the superblock, tree roots, or chunk allocation structures. If the logs indicate superblock damage, standard file extraction tools may not work, and you will need specialized rescue utilities. However, if the error is confined to user data, the recovery path is more straightforward. Always ensure you have adequate free space on a different, healthy drive to store recovered files. Do not attempt to save recovered data back onto the same corrupted partition.
Recovering Data with btrfs restore
The primary tool for extracting data from a corrupted BTRFS volume isbtrfs restore. This utility operates in read-only mode and attempts to reconstruct the directory tree structure without modifying the source disk. It is particularly effective when the filesystem metadata is partially damaged but the underlying data chunks remain intact. To use this tool, specify the source device and a destination directory on a healthy filesystem. The command syntax is btrfs restore /dev/sdX1 /path/to/backup/directory.
This process can take a significant amount of time depending on the size of the drive and the number of corrupted blocks. btrfs restore will skip unreadable files and log them to a separate error file, allowing you to continue recovering the rest of your data. It preserves permissions, timestamps, and extended attributes where possible. If you encounter errors related to device detection, such as the drive being identified as a character device rather than a block device, refer to our guide on USB Drive Detected as a Char Device on Linux: Troubleshooting Guide to ensure proper interface configuration.
Advanced Rescue Techniques
Ifbtrfs restore fails to access the filesystem structure, you may need to use btrfs rescue commands. These utilities attempt to fix low-level structural issues before data extraction becomes possible. The btrfs rescue zero-log command can clear a corrupted transaction log, which is a common cause of mount failures. Another option is btrfs rescue chunk-recover, which attempts to rebuild the chunk allocation table if it has been damaged. These commands should be used with caution, as they modify the filesystem structure. Always create a full disk image using dd before running these repairs, so you can revert if the situation worsens.
For cases where the filesystem cannot be mounted at all, consider using third-party tools like testdisk or photorec. These tools ignore filesystem structures and search for file signatures directly on the raw disk. While this method recovers files without their original directory names, it is a reliable fallback when BTRFS-specific tools fail. Additionally, if you are working with large disk images on hardware with limited resources, consult How to Mount Large Disk Image on Small Hardware to Recover Files for optimization strategies.
Preventing Future Corruption
Once your data is safe, you must address the root cause of the corruption to prevent recurrence. BTRFS relies heavily on checksums to detect bit-rot and hardware errors. Regularly scheduled scrubs are vital for maintaining health. Add a cron job to runbtrfs scrub start /mnt/your_mountpoint weekly. Ensure your system uses ECC memory if available, as RAM errors can corrupt data before it is written to disk. Also, verify that your SSDs or HDDs are not failing by checking SMART data. If you are migrating from another filesystem, review best practices for conversion, such as those outlined in How to Convert ext4 Partition on RAID 1 to btrfs, to ensure optimal initial setup.
Frequently Asked Questions
Can I mount the drive read-only to copy files?
Yes, mounting read-only is a safer intermediate step than read-write, but it does not guarantee success if metadata is broken. Use mount -o ro /dev/sdX1 /mnt/recovery to attempt access. If the mount fails due to checksum errors, fall back to btrfs restore which works on unmounted devices.
What is the difference between btrfs scrub and btrfs check?
btrfs scrub runs online while the filesystem is mounted, verifying checksums and repairing correctable errors automatically. btrfs check is an offline diagnostic tool that analyzes the filesystem structure for inconsistencies without modifying data. Use check only when the filesystem cannot be mounted.
Will btrfs restore recover deleted files?
No, btrfs restore only recovers files that still exist in the filesystem's directory tree. If you deleted files before the corruption occurred, they are likely gone unless you have snapshots enabled. Always enable periodic snapshots to protect against accidental deletion and corruption.
Is it safe to run btrfs rescue zero-log?
This command is generally safe for clearing corrupted transaction logs, which are temporary structures. However, it discards pending transactions that were not committed to disk. Use it only if the filesystem refuses to mount due to log errors, and always backup first.
How do I know if my hard drive is physically failing?
Check SMART status using smartctl -a /dev/sdX. Look for reallocated sector counts, media errors, or current temperature anomalies. Physical failures often manifest as repeated checksum errors across different files, whereas software corruption is usually localized.