Replace a failed device in a ZFS mirror

Synopsis #

This procedure is limited to replacing one failed provider in a conventional ZFS mirror that still has a healthy member. RAIDZ, special vdevs, dRAID, whole-pool migration, bootcode, encryption, and ambiguous hardware identity require a topology-specific plan.

The dangerous part is not the zpool replace syntax. It is proving which physical device failed and which new provider is safe to overwrite.

Confirm the topology and backup #

Preserve the complete pool state:

$ zpool status -P tank
$ zpool status -g tank
$ zpool list tank
$ geom disk list

The -P output records full provider paths. The separate -g output records ZFS vdev GUIDs, which remain useful when path names change. Preserve both views and correlate them with the physical serial number or enclosure slot before selecting a replacement target.

Confirm all of the following before removing hardware:

the affected top-level vdev is a mirror;
another mirror member is ONLINE and readable;
no other vdev is degraded or unavailable;
an independent backup exists and can be accessed;
the failed provider is matched to a physical serial number or enclosure slot.

If the pool is suspended, has permanent data errors, or has lost more redundancy than expected, stop. Replacing a device is not a substitute for a recovery assessment.

Record the partition layout #

Boot pools and many data pools use GPT partitions rather than whole disks. Record the healthy member’s layout and labels:

$ gpart show
$ gpart list

The replacement must be at least large enough for the intended partition. A drive sold with the same nominal capacity can contain fewer sectors.

Power down when the controller, enclosure, or operating procedure does not support safe hot replacement. After installing the new drive, identify it by serial and size before writing a partition table.

Prepare an equivalent provider #

Use the site’s recorded provisioning procedure to create the required GPT and ZFS partition on the new disk. Do not paste a device name from this guide. Verify the target immediately before every destructive gpart command.

Prefer stable GPT labels or GPT identifiers where the existing pool uses them. The final provider passed to ZFS should represent the replacement partition, not an accidental whole disk beside it.

Start the replacement #

With old-provider taken from the recorded full-path pool status and correlated with the separately recorded vdev GUID, and new-provider verified from the new partition, run:

# zpool replace tank old-provider new-provider
$ zpool status tank

ZFS begins a resilver. Monitor it without detaching the remaining healthy member:

$ zpool status -P tank

I/O errors on the surviving member during a resilver materially change the recovery risk. Preserve the status and reconsider the plan rather than repeatedly restarting commands.

Verify completion #

After the resilver completes:

$ zpool status -P -v tank

Confirm that every intended member is ONLINE, the resilver completed without data errors, and provider paths match the recorded layout. Run a later scrub according to the pool’s maintenance schedule; a completed resilver does not eliminate the need to investigate the original failure or validate the complete pool.

For a boot pool, also verify the release-specific bootcode and EFI layout before treating the new disk as independently bootable. Pool redundancy and boot redundancy are related but separate properties.