Read ZFS pool health and run a scrub

Last reviewed

13 August 2026

Applies to

15.1-RELEASE, 15.0-RELEASE, 14.4-RELEASE

Synopsis #

zpool status reports pool topology, device state, scan history, and known data errors. A scrub reads allocated data, verifies checksums, and uses available redundancy to repair damaged copies. It cannot repair data for which no valid redundant copy exists.

A pool can remain ONLINE while recording checksum errors or permanent file damage. Read the complete status rather than reducing it to the state word.

Record the status before changing it #

List pools and capture detailed status with full provider paths:

$ zpool list
$ zpool status -P
$ zpool status -v

Interpret the sections separately:

state describes pool availability;
status and action explain the current condition;
scan reports a scrub or resilver and its result;
the topology table records read, write, and checksum counters;
errors lists known permanent data errors.

Do not clear counters before preserving this evidence. Device identity, controller messages, SMART data, and /var/run/dmesg.boot may be needed to distinguish a disk fault from a cable, backplane, power, or controller problem.

Start one scrub deliberately #

If no resilver or scrub is active and the pool is stable enough to read, start a scrub:

# zpool scrub tank
$ zpool status tank

On supported releases, wait for completion when a maintenance script needs a synchronous boundary:

# zpool scrub -w tank

A scrub competes for device I/O. Monitor workload latency and pool progress, but do not repeatedly stop and restart it merely because it takes time.

Verify the result #

After completion, read the full status again:

$ zpool status -v tank

A healthy result records a completed scrub with zero errors and ends with errors: No known data errors. If blocks were repaired, investigate the affected device or path even when redundancy restored the data.

Permanent errors require recovery from an intact snapshot or backup. Removing the error record does not restore the file. The current FreeBSD ZFS chapter documents corrective receive for a matching intact snapshot, but that operation has strict dataset and snapshot requirements and should not be improvised.

Do not treat a scrub as a backup #

A scrub validates the copies already present in a pool. It does not recover deleted files, provide an earlier application state, or survive loss of the host. Pair regular scrubs with snapshots, independent replication, capacity alerts, and restore tests.

The snapshot and replication guide covers the first independent-copy workflow.

Investigate recurring counters #

When counters continue to rise:

Preserve zpool status -P -v and system logs.
Identify the physical device from serial and enclosure information.
Check cables, power, controller, and backplane alongside drive health.
Confirm that an independent backup is current.
Follow a replacement procedure appropriate to the recorded vdev topology.

Do not offline or detach a provider until the remaining topology and redundancy have been explicitly checked.