BTRFS Corrupted Volume Repair Guide

Terramaster F4-423 | TOS 6.0.783-01200

⚠️ CRITICAL: STOP IMMEDIATELY

• DO NOT WRITE to the corrupted volume
• BACKUP any accessible data before proceeding
• Power loss during operation can worsen corruption

---

Step 1: Access SSH/Terminal

ssh admin@[your-terramaster-ip]
BASH

TOS SSH Documentation

---

Step 2: Identify Volume Device

lsblk
BASH

Or:

btrfs filesystem show
BASH

Note the device path (e.g., /dev/sdX or /dev/md0)

---

Step 3: Check Mount Status

mount | grep btrfs
BASH

If mounted, note the mount point (e.g., /Volume1)

---

Step 4: Attempt Read-Only Mount (If Unmounted)

mount -o ro,usebackuproot /dev/[device] /mnt/recovery
BASH

usebackuproot documentation

If successful: Volume is recoverable, proceed to Step 5
If fails: Skip to Step 6

---

Step 5: Run BTRFS Scrub (If Mountable)

btrfs scrub start -B -r /mnt/recovery
BASH

btrfs-scrub documentation

Check status:

btrfs scrub status /mnt/recovery
BASH

If errors found:

• Exit code 3 = uncorrectable errors
• Proceed to Step 6

---

Step 6: Unmount and Run Read-Only Check

umount /mnt/recovery  # or umount /Volume1
BASH

btrfs check --readonly /dev/[device]
BASH

btrfs-check documentation

Review output for:

• Superblock errors
• Tree corruption
• Extent tree issues

---

Step 7: Attempt Superblock Recovery (If Needed)

btrfs rescue super-recover -y /dev/[device]
BASH

btrfs-rescue documentation

---

Step 8: Run Check with Backup Roots

btrfs check --backup /dev/[device]
BASH

Or try alternate superblock:

btrfs check -s 1 /dev/[device]
BASH

backup roots documentation

---

Step 9: Repair Mode (⚠️ USE WITH CAUTION)

ONLY if previous steps fail and you accept data loss risk

btrfs check --repair /dev/[device]
BASH

repair mode documentation

Warning: 10-second delay before execution
Risk: May cause additional corruption

---

Step 10: Mount and Verify

mount -o usebackuproot /dev/[device] /mnt/recovery
BASH

Check filesystem:

btrfs filesystem df /mnt/recovery
ls -la /mnt/recovery
BASH

---

Step 11: Data Recovery (Last Resort)

If volume still won't mount properly

btrfs restore -D /dev/[device] /path/to/backup/location
BASH

btrfs-restore documentation

Note: Salvages files without modifying source, may recover incomplete/older versions

---

Step 12: Post-Recovery Actions

If Successful:

# Run full scrub
btrfs scrub start -B /mnt/recovery

# Check data checksums
btrfs check --check-data-csum /dev/[device]
BASH

Backup Immediately:

rsync -avh --progress /mnt/recovery/ /path/to/backup/
BASH

Consider:

• Hardware diagnostics (SMART tests)
• UPS installation to prevent future power loss
• Regular scrub scheduling (monthly recommended)

---

Terramaster-Specific Notes

TOS GUI Access:

1. Navigate to Storage Manager → Volume
2. Right-click Volume 1 → Repair (if available)

TOS May Lock Commands:

If commands fail with "device busy":

# Stop TOS services temporarily
systemctl stop nasmanager
systemctl stop datapipeline
BASH

Re-enable after repair:

systemctl start nasmanager
systemctl start datapipeline
BASH

---

Additional Resources

• BTRFS Official Documentation
• BTRFS Scrub
• BTRFS Check
• BTRFS Rescue
• BTRFS Restore
• Terramaster Support

---

Expected Outcomes

Best Case: Superblock recovery + scrub repairs all errors
Good Case: Repair mode fixes corruption, some file timestamps may change
Acceptable Case: Restore recovers most files, some may be incomplete
Worst Case: Physical drive damage requires professional data recovery

---

Prevention for Future

1. Enable Auto-Scrub:

# Add to crontab
0 3 1 * * btrfs scrub start /Volume1
BASH

1. UPS Protection: Prevent sudden power loss

2. Regular Backups: 3-2-1 rule (3 copies, 2 media types, 1 offsite)

3. Monitor SMART:

smartctl -a /dev/sda
BASH