Finish replacement reconstruction before closing an OpenZFS disk incident

Follow the replacement through reconstruction and any concluding scrub before closing the incident.

Source facts

OpenZFS 2.3 describes device replacement as attaching the new device, waiting for reconstruction, and then detaching the old one. A replacement cancels an ongoing scrub. The new device must meet the documented minimum size for the mirror or RAID-Z configuration. Sequential reconstruction restores redundancy without verifying checksums during that stage and starts a scrub afterward; that sequential mode is not supported for RAID-Z. The command also provides a wait-for-completion option.

Source: OpenZFS 2.3 — zpool replace.

Applicability

This applies to the OpenZFS 2.3 replacement command. It addresses completion and verification stages, not a claim that an arbitrary drive model or physical slot is a supported replacement.

DSE recommendation

DSE recommends recording the failed device identity, replacement identity, pool layout, and selected reconstruction mode before the change. Keep the incident open through the required completion and health review, including any follow-on scrub. Have a second physical identification check before removing hardware. Avoid treating a command that was accepted as evidence that redundancy is restored. Escalate unexpected device sizes or pool errors before using any force option, and preserve the original status output for comparison.

Verification

Rehearse replacement in a disposable pool using the intended mode. Observe reconstruction through completion and any subsequent scrub, then inspect pool status. Confirm the record can identify which physical device changed and whether unresolved errors remain before marking the rehearsal successful.

Official reference

OpenZFS 2.3 — zpool replace. Reviewed October 15, 2026.