Recovering a ZFS Pool That Won't Import on FreeBSD

A pool that does not import may be incomplete, still active on another host, hidden behind changed device paths, incompatible with the rescue kernel, damaged in recent transaction groups, or attached through failing hardware. ZFS recovery flags are not a ladder to run from mild to extreme. Some discard transactions or override ownership safeguards. Preserve evidence and stabilize hardware before any import that can write.

Inventory hardware before asking ZFS to repair anything

Record the FreeBSD/OpenZFS environment and all visible storage:

freebsd-version -kru
zpool version
camcontrol devlist
geom disk list
gpart show -p
dmesg | grep -i -E 'error|timeout|reset|nvme|da[0-9]|ada[0-9]'

Match disks by serial, GPT label, enclosure slot, and capacity—not transient da0 order. If devices disappear, reset, or report read errors, stop import attempts and address power, cabling, controller, enclosure, or media failure. Repeated full scans can stress a dying disk. Create forensic images or hardware clones first when the remaining copy is irreplaceable.

List import candidates without importing:

zpool import
zpool import -d /dev/gpt

The second command narrows scanning to persistent GPT labels when that matches the system. A pool absent from the first output may still have labels outside the default search path. Use -d deliberately rather than pointing ZFS at arbitrary files.

zdb -l reads ZFS labels from a specific provider and can identify pool GUID, vdev GUID, and configuration copies:

zdb -l /dev/gpt/tank0

It does not prove the entire pool is consistent. Preserve the output from every expected member and compare the topology with build records.

Interpret status and topology before choosing a flag

UNAVAIL means the discovered top-level vdev set cannot provide the pool. A missing side of a mirror may still leave enough data; a missing single-disk top-level vdev or too many members of a RAID-Z group may not. Redundancy is per vdev, so healthy disks elsewhere in the pool cannot replace a required missing vdev.

If more than one pool uses the same name, import by the numeric pool GUID shown by zpool import and optionally assign a temporary new name:

zpool import 4519283746192837465 recovery_tank

That command performs a real import. Use it only after deciding normal read-write import is safe. A name collision is not corruption and does not justify -F or -X.

Check whether the pool is genuinely active on another cluster node, hypervisor, or storage host. The -f flag overrides the “potentially active” safeguard; it does not repair an unclean shutdown. Importing writable on two hosts can destroy the pool. Fence the old host and storage path before considering -f, and document why exclusivity is proven.

Perform the least-writing useful import

For an importable pool with questionable health, begin without mounting datasets and with the pool read-only:

mkdir -p /mnt/recovery
zpool import -N -o readonly=on -R /mnt/recovery tank
zpool status -v tank
zpool events -v

-N prevents dataset mounts. readonly=on prevents pool modifications, and -R supplies an alternate root while setting cachefile=none for the import. Confirm these properties in the actual output. Encrypted datasets remain unavailable until keys are deliberately loaded.

If status is coherent and hardware is stable, decide whether to export and re-import read-only with selected datasets mounted under the alternate root for copying. Never mount over the rescue system’s /, /usr, or /var. Copy the most irreplaceable data first and verify the backup before attempting repair or a scrub.

A read-only import is not zero I/O—it reads metadata and data—and failing drives can worsen. Prioritize imaging when hardware telemetry is bad.

Treat missing logs and rewind as data-loss decisions

The -m import option allows import with a missing separate log device and discards that log. The manual explicitly warns that recent transactions can be lost. Use it only after proving the missing device cannot be restored, understanding the workload’s synchronous-write guarantees, and preserving all remaining media.

Recovery mode -F searches for an earlier transaction group that can make a non-importable pool importable. Dry-run first:

zpool import -nF tank

The dry run reports whether recovery may work without applying it. A real -F import rolls the pool back and discards transactions after the selected point. Do not run it until backups/images exist and the expected loss is acceptable.

-X enables extreme rewind search with -F. It can be slow, can choose a much older transaction group, and can discard substantial recent data. It is not “the next safe command.” Escalate with FreeBSD/OpenZFS expertise and cloned media. Likewise, selecting a specific transaction group with -T is expert recovery, not a generic tutorial step.

If a valid pool checkpoint exists, --rewind-to-checkpoint can expose that historical state read-only for evaluation; a writable checkpoint rewind is irreversible and discards everything written after the checkpoint. Read the exact zpool-import(8) semantics before using it.

Avoid commands that erase recovery evidence

During diagnosis, do not run:

zpool create on any member;
zpool labelclear;
gpart destroy or repartitioning;
zpool upgrade;
broad zpool import -a -f;
zpool clear merely to hide counters.

Labels, history, error counts, and old transaction groups are evidence. Clearing or overwriting them can make a specialist’s later recovery impossible. A pool feature upgrade can also prevent import by older rescue media without fixing the current problem.

Do not start a scrub before copying data from a fragile pool. A scrub reads every allocated block and may increase stress; on a redundant writable pool it can also repair from good copies. That is valuable after hardware is stable and backups exist, not as the first import test.

Validate recovered data and rebuild confidence

For read-only recovery, copy data to a separate failure domain, verify hashes or application-level backups, and test representative restores. zpool status saying “ONLINE” means the topology is available, not that every historical file is correct or every application transaction is consistent.

If the pool returns to writable service, replace failing hardware, run a scrub under monitoring, review zpool status -v and events, and investigate every checksum/read/write error. Recreate bootcode if this is a boot pool and the recovery environment changed it, following the target release’s instructions.

Finally, document the original topology, device identities, failed state, every command, import mode, discarded transaction window, and recovered files. The safest ZFS recovery is not the one with the most aggressive flag; it is the one that preserves the greatest number of future options while extracting verified data.

Related:

Sources: