dmesg and attempting to mount the filesystem in read-only mode to prevent further damage. If standard mounting fails, use specialized tools like btrfs rescue commands to repair superblocks or scan for valid tree roots before proceeding with more aggressive recovery methods.
Initial Assessment and Safety Measures
Before attempting any repairs, it is crucial to assess the current state of the storage device. The first step is to verify that the kernel recognizes the block device. Use the lsblk command to list all block devices and identify your BTRFS partition. Look for entries that show the filesystem type as btrfs. If the device appears but shows no filesystem, the partition table might be damaged or the filesystem header corrupted.
Next, check the system journal for errors related to the specific device. Run dmesg | grep btrfs to view recent kernel messages. This output often reveals if there are I/O errors, bad sectors, or checksum mismatches. If you see repeated I/O errors, the underlying hardware may be failing, and you should prioritize cloning the disk using ddrescue before attempting software-level repairs. Working on a physically failing drive can accelerate its death and make data recovery impossible.
Always create a backup image of the affected partition before running any repair commands. You can use dd or cp to copy the entire partition to another safe location. For example, sudo dd if=/dev/sdXN of=/path/to/backup.img bs=4M status=progress. This safety net ensures that if a repair command corrupts the filesystem further, you can restore the original state and try a different approach.
Attempting Standard Mounting Procedures
Often, a BTRFS partition becomes inaccessible due to minor inconsistencies rather than catastrophic failure. The most common initial fix is to attempt mounting the filesystem with specific options that allow the kernel to handle errors gracefully. Try mounting the partition in read-only mode first to access your data without risking write operations.
Use the command sudo mount -o ro /dev/sdXN /mnt/recovery. Replace /dev/sdXN with your actual device identifier and /mnt/recovery with your desired mount point. If this succeeds, immediately copy your critical data to another drive. Read-only access prevents the filesystem from marking chunks as dirty or allocating new blocks, which could exacerbate existing issues.
If read-only mounting fails, you might need to use the -o ro,skip_balance option. Sometimes, an ongoing balance operation can lock the filesystem or cause timeouts during mount attempts. Adding skip_balance tells the kernel to ignore pending balance operations and mount the filesystem anyway. Another useful flag is -o degraded, which allows mounting even if one or more devices in a RAID configuration are missing or offline. This is particularly relevant if you are dealing with a multi-disk array where one drive has failed.
Using BTRFS Rescue Commands
When standard mounting options fail, the btrfs rescue subcommand provides powerful tools for fixing common metadata issues. These commands operate at a lower level than the kernel mount process and can repair superblocks, clear csum errors, and search for valid tree roots. Always run these commands against the raw device or partition, not a mounted volume.
The first command to try is btrfs rescue super-recover /dev/sdXN. This tool searches for backup copies of the superblock within the filesystem. BTRFS stores multiple copies of the superblock across the disk; if the primary one is corrupted, this command can restore it from a backup. After running this, attempt to mount the filesystem again. If successful, the issue was likely a single-point failure in the superblock structure.
If superblock recovery does not work, try btrfs rescue chunk-recover /dev/sdXN. This command scans the disk for valid extent trees and attempts to reconstruct the chunk allocation tree. It is effective when the filesystem cannot find its data locations due to corruption in the root tree. Note that this process can take a long time depending on the size of the partition and the speed of the storage media. Monitor the progress via system logs.
Another critical tool is btrfs rescue zero-log. This clears the transaction log, which can sometimes become inconsistent after an unclean shutdown. While less common than superblock issues, a corrupted log can prevent the filesystem from mounting entirely. After clearing the log, try mounting the filesystem again. If none of these rescue commands succeed, the corruption may be too severe for automatic repair.
Advanced Recovery and Data Extraction
If automated rescue commands fail, you may need to manually extract data using forensic techniques. Tools like btrfs-find-root can help locate valid tree roots on the disk. By specifying a candidate root object ID, you can test if the filesystem structure is intact at that location. Once a valid root is found, you can use btrfs restore to copy files out of the damaged filesystem.
The btrfs restore command works by scanning the disk for valid extents and rebuilding the directory structure in memory. It outputs the recovered files to a specified directory. For example, btrfs restore /dev/sdXN /path/to/output. This tool is non-destructive and reads only the necessary extents, making it safe to use on unstable filesystems. However, it may not recover all files if their extents are severely fragmented or overwritten.
In cases where the partition is part of a larger RAID setup, refer to our guide on Evaluating Options for Replacing Failed Home NAS Array: BTRFS RAID Configuration and Replacement Ability. Understanding how your RAID profile (such as RAID1, RAID5, or RAID6) affects data distribution is key to recovering individual files. If you are working with virtual disk images, such as VDI files from virtual machines, check out How to Recover Corrupted btrfs Data from a VDI File in Linux for specific instructions on handling loop devices and image-based recovery.
Prevention and Best Practices
Preventing future BTRFS failures involves regular maintenance and proper configuration. Enable Scrubbing to detect and correct silent data corruption. Schedule monthly scrubs using systemd timers or cron jobs. The command btrfs scrub start /mount/point checks every block for checksum errors and repairs them if parity information is available in a RAID setup.
Ensure you have adequate backups. BTRFS protects against bit rot and metadata corruption, but it is not a substitute for backups. Implement the 3-2-1 rule: three copies of your data, on two different media, with one offsite. Regularly test your backups to ensure they are restorable. Additionally, keep your kernel and BTRFS utilities updated to benefit from the latest bug fixes and performance improvements.
Frequently Asked Questions
Can I recover data if the BTRFS partition is formatted?
Yes, but it is significantly harder. If the partition was recently formatted, the old metadata might still exist on the disk until overwritten. Use testdisk or photorec to search for file signatures. BTRFS-specific tools may struggle because the filesystem structures are intentionally wiped. Immediate action is critical to prevent new data from overwriting the lost structures.
What causes BTRFS to become read-only automatically?
BTRFS switches to read-only mode when it detects severe metadata corruption or hardware I/O errors. This is a protective mechanism to prevent further damage. Check dmesg for the specific error message triggering this state. Resolving the underlying hardware issue or repairing the metadata usually allows you to remount the filesystem in read-write mode.
Is it safe to run btrfs rescue on a live system?
No, never run rescue commands on a mounted filesystem. Doing so can lead to inconsistent states and data loss. Always boot from a live USB or rescue environment, ensuring the target partition is not mounted. This guarantees that no other processes are writing to the disk while you attempt repairs.
How do I know if my BTRFS RAID is degraded?
Run btrfs filesystem show to view the status of all devices in the filesystem. A degraded RAID will indicate missing or failed devices. You can also check cat /proc/mounts for the degraded mount option. If the system is running in degraded mode, replace the failed drive as soon as possible to restore redundancy.
Can I convert a damaged BTRFS partition to ext4?
You cannot directly convert a damaged BTRFS partition to ext4. First, you must recover the data using BTRFS tools or third-party recovery software. Once the data is safely extracted, you can format the partition as ext4 and restore the files. Direct conversion is not supported because the filesystem structures are fundamentally different.