BTRFS checksum mismatches often corrupt files downloaded via Transmission if the filesystem is not properly scrubbed or if write caching causes data inconsistency. The primary solution involves verifying the integrity of the affected file using btrfs verify and running a full btrfs scrub to detect and repair silent corruption on disk.
Understanding the Corruption Mechanism
When you download large video files using BitTorrent clients like Transmission, the data arrives in small chunks. BTRFS calculates checksums for every block of data written to the disk. If a power loss occurs during writing, or if there is a bug in the kernel's page cache handling, the final file may have valid metadata but corrupted data blocks. This results in a file that exists but cannot be played by players like Celluloid or VLC.
This issue is distinct from simple file deletion errors. As noted in related discussions about BTRFS: Persisting Deleted Files Scrub Errors, scrubbing is primarily a detection tool. It identifies where checksums do not match the stored data. It does not automatically "fix" corruption unless redundant copies exist (e.g., RAID 1, RAID 5/6/10) or the data can be re-downloaded. For single-disk setups, scrubbing tells you *what* is broken; it does not magically restore the bytes.
Why Transmission Might Trigger This
Transmission itself is generally reliable, but Linux kernel behavior regarding dirty pages can cause issues. If the system runs out of memory or if the vm.dirty_ratio settings are too aggressive, data might be flushed to disk in a way that BTRFS struggles to verify immediately. Additionally, if the download was interrupted abruptly, the torrent client might mark the file as complete before all pieces are verified against the info-hash.
Detecting the Corrupted File
The first step is to confirm that BTRFS has detected the error. You can check the system logs for messages indicating checksum failures.
- Run
dmesg | grep btrfsto look for recent errors. - Look for lines containing "checksum error" or "failed to read chunk."
- If no logs appear, initiate a manual verification of the specific file.
To verify a single file, use the following command:
btrfs verify /path/to/corrupted/video.mp4If the output reports a checksum mismatch, the file is indeed corrupted at the filesystem level. Note that this process reads the data blocks and compares them against the checksums stored in the BTRFS tree. It does not modify the file; it only reports the status.
Repairing Single-Disk Corruption
If you are running BTRFS on a single disk without redundancy, BTRFS cannot reconstruct the missing bits from parity or mirrors. In this scenario, "repair" means replacing the bad data with good data. Since the data came from a torrent, the most effective repair method is to force the BitTorrent client to re-download the corrupted portion.
Step-by-Step Re-download
- Stop the download: Pause or remove the torrent from Transmission temporarily.
- Delete the local data: Remove the corrupted file from your drive. Do not just move it; delete it so BTRFS frees the extents.
- Force verification: Some versions of Transmission allow you to right-click the torrent and select "Verify Data" or "Re-check." This forces the client to compare local hashes with the tracker's info-hash.
- Resume download: Allow Transmission to re-download the file. Ensure you are connected to enough peers to guarantee data integrity.
This approach leverages the nature of BitTorrent: the network holds the correct copy. By deleting the bad local copy and re-verifying, you ensure that only valid data is written back to the BTRFS filesystem.
Preventing Future Occurrences
To minimize the risk of future corruption, consider adjusting how your system handles writes and checks.
Enable Regular Scrubs
Even though scrubbing doesn't fix single-disk errors, it helps identify issues early. Set up a monthly cron job to run:
btrfs scrub start /mount/pointMonitor the progress with btrfs scrub status /mount/point. If errors are found frequently, investigate hardware health (SMART data) as faulty disks can cause random bit flips.
Adjust Write Caching
If you experience frequent corruption, try disabling write-back caching for the disk. Edit /etc/fstab and add the nobarrier option to your BTRFS mount options, although this is generally discouraged for safety. A safer alternative is to ensure your UPS is functional and that the system shuts down cleanly.
Use Checksums for Verification
For critical media, consider using tools like btcheck or enabling hash checking in Transmission preferences. This ensures that the client validates the hash of each piece before marking it as complete.
When to Worry About Hardware Failure
If you see repeated checksum errors across different files, not just those downloaded via BT, your storage medium may be failing. BTRFS is designed to catch these errors. Unlike ext4, which might silently write garbage data, BTRFS will refuse to read corrupted blocks if the checksum fails. If scrubbing reveals widespread errors, replace the drive immediately. For more complex recovery scenarios involving encrypted partitions, refer to guides on Recovering Damaged LUKS-Encrypted BTRFS Partition in Virtual Machine.
Frequently Asked Questions
Does btrfs scrub fix corrupted files?
No, scrubbing only detects errors. On a single-disk setup, it cannot repair data because there are no redundant copies. It must report the error so you can take action, such as re-downloading the file.
Why do only some video files break?
Corruption often happens when the system crashes or loses power during the final flush of data. Files that were fully completed and verified by the torrent client before shutdown are less likely to be affected than those still being finalized.
Can I recover the video using testdisk?
TestDisk is designed for partition table recovery and undeleting files. It cannot repair corrupted data blocks within an existing file. You need to replace the bad data, typically by re-downloading it.
Is nobarrier safe to use?
Using nobarrier disables write barriers, which can improve performance but significantly increases the risk of data corruption during power loss. It is not recommended for general use unless you have a UPS and understand the risks.
How do I check if my disk is failing?
Run smartctl -a /dev/sdX (replacing sdX with your device). Look for reallocated sector counts or pending failures. Frequent BTRFS checksum errors combined with SMART warnings indicate imminent hardware failure.