FreeBSD 12 – recurring ZFS checksum errors during scrub – Fix & Prevention

📖 ~1 min read

Table of contents

1. Symptom & Impact
2. Environment & Reproduction
3. Root Cause Analysis
4. Quick Triage
5. Step-by-Step Diagnosis
6. Solution – Primary Fix
7. Solution – Alternative Approaches
8. Verification & Acceptance Criteria
9. Rollback Plan
10. Prevention & Hardening
11. Related Errors & Cross-Refs
12. References & Further Reading

Symptom & Impact

Scrub reports persistent checksum faults, indicating potential silent data corruption risk.

Environment & Reproduction

Most common on aging disks, bad HBAs, or unstable cabling.

zpool scrub tank
zpool status -v
zpool events -v | tail -n 80

Root Cause Analysis

Checksum errors originate from media failures, controller instability, or memory corruption paths.

Quick Triage

Identify affected vdevs and recent hardware error bursts.

zpool status -v
smartctl -a /dev/da1 | grep -iE 'error|reallocated|pending'
dmesg | grep -iE 'cam|I/O error'

Step-by-Step Diagnosis

Correlate ZFS events with SMART telemetry and controller logs.

zpool events -v | tail -n 200
smartctl -x /dev/da1 | head -n 120
camcontrol inquiry da1

Solution – Primary Fix

Replace failing hardware path and run follow-up scrub until clean.

zpool replace tank gpt/disk-bad gpt/disk-good
zpool scrub tank
watch -n 30 zpool status -v

Solution – Alternative Approaches

If errors are transient, reseat cables and firmware-update controller before disk replacement.

camcontrol reset da1
shutdown -r now

Verification & Acceptance Criteria

Consecutive scrubs complete with zero new checksum errors.

zpool status -x
zpool status -v
zpool history | tail -n 20

Rollback Plan

Keep replaced disk read-only for forensic comparison if data anomalies continue.

zpool detach tank gpt/disk-good 2>/dev/null || true

Prevention & Hardening

Schedule periodic scrubs and SMART monitoring with alerting.

sysrc zfs_enable="YES"
smartctl --scan

Related Errors & Cross-Refs

Related to pool degraded states, resilver stalls, and controller timeout storms.

Related tutorial: View the step-by-step tutorial for FreeBSD 12.

View all FreeBSD 12 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

OpenZFS integrity model and FreeBSD storage reliability references.