BTRFS RAID arrays can often survive a single disk failure without data loss, but replacing the failed drive requires specific command-line steps. You must identify the faulty device, remove it from the filesystem, and add a new one to restore redundancy. This process ensures your home NAS remains protected against future hardware issues while maintaining access to your stored files.
Assessing the Failure Scenario
Before attempting any repairs, you need to confirm that the array is indeed degraded and identify which specific component has failed. BTRFS provides robust tools for this diagnostic phase. Start by checking the status of your filesystem using the
btrfs filesystem show command. This output will list all devices associated with the filesystem and highlight any missing or failed members. Look for lines indicating "missing" or errors related to a specific device path, such as
/dev/sdb1.
If you are running a RAID 1 (mirrored) or RAID 5/6 configuration, the system should still be readable despite the failure. However, write operations might be restricted or risky until the redundancy is restored. It is crucial to avoid writing new large files to the degraded array if possible, as this increases the risk of further corruption during the rebuild process. If the array does not mount automatically, you may need to use the
-o degraded option when mounting the filesystem manually. For example:
mount -o degraded /dev/sdX1 /mnt/nas. This tells the kernel to proceed even though one member of the RAID set is unavailable.
Identifying the Failed Device
Once you have accessed the data, you must precisely identify the device that needs replacement. Use
btrfs device stats /mnt/nas to view error counts for each device in the array. The device with high error counts or those marked as offline is your candidate for removal. Ensure you physically verify which drive corresponds to the failing device before proceeding. Disconnecting the wrong drive could result in permanent data loss if the array relies on that specific mirror or parity block.
It is also wise to check the SMART status of the suspected drive using
smartctl -a /dev/sdX. While BTRFS handles logical errors, physical media degradation often correlates with filesystem errors. If the drive shows signs of imminent failure, such as reallocated sector counts increasing rapidly, replace it immediately rather than trying to repair it.
BTRFS RAID 5/6 Auto-Healing: A Comprehensive Guide explains how the filesystem attempts to correct errors automatically, but these mechanisms fail when an entire device disappears from the system. Understanding this limitation is key to manual intervention.
Removing the Failed Drive
With the faulty device identified and verified, the next step is to remove it from the BTRFS volume. Use the
btrfs device delete /dev/sdX_missing /mnt/nas command. Replace
/dev/sdX_missing with the actual identifier of the missing or failed partition. This command updates the filesystem metadata to acknowledge that the device is no longer part of the active array.
The deletion process is typically fast because it only involves updating metadata structures, not wiping the physical disk. Once completed, the filesystem will remain in a degraded state, meaning it has reduced redundancy. For RAID 1, you have no mirrors left for the affected data. For RAID 5/6, you have lost one level of protection. Do not attempt to add a new drive yet; ensure the filesystem is stable and fully accessible first.
Adding the Replacement Drive
Now you can introduce the new storage device. Prepare the new drive by creating a partition table that matches the existing drives. Ideally, use
fdisk or
parted to create a single primary partition covering the entire drive. Ensure the partition type is set correctly, although BTRFS is flexible, consistency helps with management scripts.
Add the new partition to the filesystem using
btrfs device add /dev/sdY1 /mnt/nas. After adding the device, you must trigger the balancing process to redistribute data onto the new drive. Run
btrfs balance start /mnt/nas. This command moves chunks of data around to utilize the new space and restore the RAID profile's redundancy.
The balance operation can take hours or days depending on the size of the dataset and the speed of the disks. Monitor progress with
btrfs balance status /mnt/nas. During this time, avoid heavy write loads to minimize the duration of the rebalancing process. Once the balance completes, the array will return to its healthy, redundant state.
For users migrating away from complex setups, understanding alternative RAID implementations can be beneficial. See
Migrating BTRFS Profiles to mdadm RAID: A Home NAS Setup Guide for comparisons on stability and recovery workflows.
Verifying Data Integrity
After the replacement and rebalancing are complete, verify that the data is intact. Perform a sample read of critical files to ensure they open correctly. You can also run
btrfs scrub start /mnt/nas to initiate a full checksum verification of all data on the filesystem. Scrubbing reads every block, compares it against its checksum, and fixes any bit-rot errors found. This step confirms that the replacement process did not introduce any silent corruption.
Regular maintenance and monitoring are essential for long-term reliability. Set up alerts for disk health via SMART notifications and periodically check the BTRFS status. Keeping backups offsite remains the best defense against catastrophic failures that even RAID cannot prevent.
Frequently Asked Questions
Can I recover data if both drives in a RAID 1 pair fail?
No, if both mirrored drives fail simultaneously, data recovery is extremely difficult and usually requires professional services. BTRFS RAID 1 relies on having at least one intact copy of the data blocks. Always maintain separate backups outside the RAID array.
How long does the btrfs balance command take?
The duration depends on the total amount of data and the I/O speed of your disks. For a multi-terabyte array, it can take several hours to days. Use the status command to monitor progress and avoid interrupting the process.
What if the new drive has a different size than the old one?
BTRFS supports mixed-size drives, but the new drive will not contribute extra capacity until the balance operation distributes data evenly. The array will function normally, but utilization may be uneven until rebalancing finishes.
Is it safe to use the NAS during the replacement process?
You can read data safely while the array is degraded, but write operations carry a higher risk. Limit writes during the balance phase to reduce load and speed up the restoration of full redundancy.
What happens if I lose two drives in a RAID 5 array?
RAID 5 can only tolerate one drive failure. Losing two drives results in complete data loss for that filesystem. Consider using RAID 6, which tolerates two simultaneous drive failures, for larger arrays with multiple disks.