How to Recover Corrupted btrfs Data from a VDI File in Linux

Recovering corrupted btrfs data from a VirtualBox VDI file in Linux requires mounting the virtual disk image directly to access the underlying filesystem structure. By using tools like qemu-nbd or loop devices, you can expose the VDI contents as a block device, allowing standard recovery utilities to scan for lost files and repair metadata errors without affecting the original virtual machine state.

Understanding the VDI Structure and Corruption Symptoms

A VirtualBox Disk Image (VDI) is a container format that holds the raw bytes of a virtual hard drive. When a btrfs filesystem inside this container becomes corrupted, symptoms often include the virtual machine failing to boot, showing "Read-only file system" errors, or reporting missing chunks during scrub operations. Unlike physical drives, the corruption is isolated within the single file, which simplifies backup but complicates direct access because the host operating system does not natively understand the VDI wrapper format. The first step is recognizing that you cannot simply mount a .vdi file with the standard mount command. The hypervisor-specific header must be bypassed or converted so that Linux sees it as a standard block device containing partitions and filesystems. This distinction is critical because attempting to mount it directly will result in an "Unknown filesystem type" error.

Converting or Attaching the VDI File

To interact with the btrfs partition, you must first make the VDI file visible to the kernel as a block device. There are two primary methods for achieving this: converting the image or attaching it via a network block device driver. The most robust method involves using qemu-nbd, which is part of the QEMU package suite. This tool allows you to attach a disk image to a nbd (Network Block Device) interface. First, ensure the nbd module is loaded by running sudo modprobe nbd max_part=8. Then, execute the following command to attach your VDI file:

sudo qemu-nbd --connect=/dev/nbd0 /path/to/your/disk.vdi

This command exposes the VDI contents at /dev/nbd0. If your VDI contains multiple partitions, they may appear as /dev/nbd0p1, /dev/nbd0p2, etc. You can verify the partition layout using fdisk -l /dev/nbd0 or lsblk. Alternatively, if qemu-nbd is unavailable, you can convert the VDI to a raw image using VBoxManage:

VBoxManage clonemedium disk source.vdi destination.raw --format raw

Once converted, you can use a loop device to attach the raw image:

sudo losetup -fP /path/to/destination.raw

This creates a new block device (e.g., /dev/loop0) with partition awareness enabled due to the -P flag.

Checking for Related Issues

Before proceeding with recovery, it is wise to check if the issue stems from size mismatches or encryption layers. If the VM was resized incorrectly, the virtual size might not match the actual allocated space, leading to I/O errors. For more on this, see VM QEMU not recognizing virtual size. Additionally, if the btrfs partition was encrypted with LUKS, you must unlock the volume before accessing the filesystem. See Recovering Damaged LUKS-Encrypted BTRFS Partition in Virtual Machine for guidance on handling encrypted containers.

Scanning and Repairing the btrfs Filesystem

Once the block device representing the btrfs partition is identified (let us assume it is /dev/nbd0p1), you can begin the diagnostic and repair process. Always start with a read-only check to assess the damage without risking further writes. Run the following command to scan the filesystem:

sudo btrfs rescue zero-log /dev/nbd0p1

The btrfs rescue zero-log command attempts to fix issues where the log tree is corrupted, which is a common cause of mount failures. If this succeeds, try mounting the filesystem in read-only mode to verify accessibility:

sudo mount -o ro /dev/nbd0p1 /mnt/recovery

If the filesystem mounts successfully, immediately copy your critical data to a safe location on your host machine. Do not attempt to write back to the VDI until you have secured your data. If the filesystem refuses to mount even in read-only mode, proceed with a deeper repair using the btrfs check utility. Note that this operation can take a long time depending on the size of the disk.

sudo btrfs check --readonly /dev/nbd0p1

Use the --readonly flag initially to get a detailed report of errors such as missing chunks, bad superblocks, or extent tree issues. If the report indicates correctable errors, you can run the repair command without the readonly flag, but this carries a risk of data loss if the corruption is severe.

sudo btrfs check --repair /dev/nbd0p1

After running the repair, attempt to mount the filesystem again. If it mounts, copy your data out immediately.

Data Extraction and Verification

With the filesystem mounted, navigate to /mnt/recovery and use standard Linux commands like cp or rsync to extract your files. It is advisable to use rsync with the -av flags to preserve permissions and attributes while providing verbose output to catch any transfer errors.

rsync -av /mnt/recovery/ /path/to/safe/backup/

Verify the integrity of the copied files by checking checksums if available. Once the data is safely backed up, you can choose to recreate the virtual machine from scratch using the recovered data, rather than trying to fix the potentially unstable original VDI file. This approach minimizes the risk of future corruption spreading. For cases where standard btrfs tools fail to recover the partition entirely, consider specialized recovery software designed for damaged btrfs structures. Learn more about alternative approaches in Unable to Recover Btrfs Partition: What to Do?.

Frequently Asked Questions

Can I recover btrfs data if the superblock is completely destroyed?

Yes, btrfs stores multiple copies of the superblock across the disk. If the primary superblock is corrupted, the filesystem can often still be mounted by specifying the offset of a backup superblock using the sb= mount option. However, if all superblocks are lost, professional data recovery services or specialized tools may be required to reconstruct the metadata headers from the raw disk data.

Why did my VDI file become corrupted in the first place?

Corruption typically occurs due to unclean shutdowns, such as power failures or forced VM termination, which leave the filesystem in an inconsistent state. Host storage errors, bad sectors on the physical drive hosting the VDI, or bugs in the virtualization software can also contribute. Ensuring proper shutdown procedures and regular backups of the VDI file itself can mitigate these risks significantly.

Is it safe to run btrfs check --repair on my production data?

No, running btrfs check --repair modifies the filesystem structures and carries a risk of further data loss if the corruption is complex or if there are conflicting metadata entries. Always perform a full backup of the VDI file and attempt to mount it read-only first. Use the repair command only as a last resort after exhausting read-only diagnostic options and securing any accessible data.

What should I do if qemu-nbd fails to load the VDI?

If qemu-nbd fails, ensure that the nbd kernel module is loaded and that you have sufficient permissions. Check the system logs with dmesg for specific error messages related to NBD connection failures. Alternatively, convert the VDI to a raw image using VBoxManage and attach it using a loop device, which is a more universally supported method across different Linux distributions.

How can I prevent btrfs corruption in future virtual machines?

Preventive measures include enabling regular snapshots and scrubs to detect early signs of metadata rot. Ensure that the host system has reliable power management and that the VM is shut down gracefully rather than being powered off abruptly. Additionally, keeping your virtualization platform and guest kernel updated ensures that known filesystem bugs are patched, reducing the likelihood of corruption events.