FreeBSD 15 – ZFS pool degraded after device replacement mismatch – 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

Storage redundancy is reduced, increasing risk of data loss during additional disk failures.

Environment & Reproduction

Happens after hot-swap replacement with wrong target device or GPT label mismatch.

zpool status -v
glabel status
gpart show

Root Cause Analysis

Replacement operation points at unintended disk path or incompatible partition geometry.

Quick Triage

Confirm failed vdev identity and replacement candidate mapping.

zpool status pool0
camcontrol devlist
smartctl -a /dev/da0 | head -n 40

Step-by-Step Diagnosis

Trace by-id labels and verify ashift and partition layout alignment.

zdb -C pool0 | head -n 120
ls -l /dev/gpt
gpart show da0

Solution – Primary Fix

Offline failed device, replace with correct target, and monitor resilver.

zpool offline pool0 gpt/disk-old
zpool replace pool0 gpt/disk-old gpt/disk-new
zpool status -v

Solution – Alternative Approaches

Attach temporary mirror before replacement to preserve redundancy during maintenance.

zpool attach pool0 gpt/disk-a gpt/disk-temp
zpool status

Verification & Acceptance Criteria

Pool returns ONLINE with no checksum/read/write errors after resilver.

zpool status -x
zpool status -v
zpool iostat -v 2 5

Rollback Plan

Detach incorrect replacement and restore previous known-good topology.

zpool detach pool0 gpt/disk-new
zpool online pool0 gpt/disk-old

Prevention & Hardening

Use persistent GPT labels and standardized replacement runbooks.

glabel status
zpool get autoreplace pool0

Related Errors & Cross-Refs

Often appears with enclosure slot mapping errors and stale device nodes.

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

View all FreeBSD 15 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

OpenZFS device replacement and resilver operational guidance.