FreeBSD 12 – Common Problem 008 – ZFS Pool Enters DEGRADED State

📖 ~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

Pool reports degraded redundancy, increasing data loss risk on additional failure.

Environment & Reproduction

Common on aging disks or unstable HBA links under load.

Root Cause Analysis

Checksum errors, unreadable sectors, or detached vdevs trigger degraded status.

Quick Triage

Assess pool health immediately.

zpool status -x
zpool status
zpool iostat -v 1 3

Step-by-Step Diagnosis

Map failing device and inspect SMART data.

zpool status -P
camcontrol devlist
smartctl -a /dev/ada1

Solution – Primary Fix

Offline bad device, replace disk, and trigger resilver.

zpool offline tank /dev/ada1
zpool replace tank /dev/ada1 /dev/ada3
zpool status

Solution – Alternative Approaches

If transient cabling issue, reseat cable and run scrub before replacement.

Verification & Acceptance Criteria

Pool returns to `ONLINE`, resilver completes, and error counters remain stable.

Rollback Plan

Reattach original device if replacement is faulty and revert hardware change ticket.

Prevention & Hardening

Schedule monthly `zpool scrub`, monitor SMART, and keep spare drives available.

Related Errors & Cross-Refs

`too many errors`, `DEGRADED`, `cannot open` vdev messages.

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

`zpool(8)`, `zfs(8)`, OpenZFS admin guide.