ZFS cannot import pool: missing devices, a damaged label, and root-pool boot failure

zpool import fails and the pool refuses to come online. The error is one of a small set: cannot import 'tank': no such pool available, one or more devices is currently unavailable, cannot import 'tank': insufficient replicas, or a complaint about an unsupported version or feature. Each message points at a different stage of the import process, and each has a different recovery path.

For a data pool this is an availability incident. For a root-on-ZFS system it is worse: the import happens inside initramfs, and a failure there means the machine does not boot at all. The initramfs message cannot import rpool: no such pool available is the same class of problem with a much higher cost.

This guide covers what import actually does, how to tell the failure modes apart, and the recovery commands in order from safest to most destructive. Do not start with -F. Several of the recovery flags discard committed data, and the difference between -f and -F is one of the most common operator errors in ZFS recovery.

What this means

Import is not a single operation. ZFS has to succeed at each of these steps:

1. Find the devices. ZFS scans block devices (via libblkid on Linux) and reads the vdev labels. Each device carries four label copies, two at the start and two at the end of the device, so a partial overwrite does not normally kill the pool.
2. Assemble the vdev topology. The labels describe which devices belong to the pool and in what arrangement. If too few devices of a vdev are present, the pool has “insufficient replicas” and cannot open.
3. Read the uberblock. The uberblock ring points to the most recent transaction group (txg). ZFS picks the best valid copy.
4. Check compatibility. The pool’s feature flags must be supported by the importing ZFS. A pool upgraded on a newer OpenZFS cannot be imported by an older one. There is no downgrade.
5. Replay state. After an unclean shutdown, the ZIL is replayed and dirty state is reconciled. On pools with large ZIL replays, many datasets, or heavily fragmented space maps, this step can take minutes and look like a hang. It is usually progress, not a stall.

Each failure mode below maps to one of these stages. Identifying which stage failed is the diagnosis.

Common causes

Quick checks

All of these are read-only scans. None of them modify the pool.

# Scan for importable pools without importing anything.
# Prints pools, device states, and the reason a pool cannot be imported.
zpool import

# Rescan using persistent device names. If the pool was created with
# /dev/sdX names and the kernel renumbered the disks, this finds it.
zpool import -d /dev/disk/by-id

# Confirm which physical devices the kernel actually sees
ls -l /dev/disk/by-id/

# Dump the vdev labels of a suspected member (four copies per device).
# A device with all labels unreadable explains "no such pool available".
zdb -l /dev/disk/by-id/ata-XXXX-part1

# Kernel and ZFS module messages from the failed import attempt
dmesg | grep -i -E "zfs|spl|zio"

# ZFS internal debug log: state transitions and error recovery decisions
tail -50 /proc/spl/kstat/zfs/dbgmsg

# Recent ZFS events (import attempts, probe failures, I/O failures)
zpool events -v | tail -30

Two things to look for in the zpool import scan output: the per-device state column (ONLINE vs UNAVAIL per vdev member) and any line saying the pool “may be in use on another system”. The first tells you whether you have a naming problem or a real hardware absence. The second tells you the pool was not cleanly exported, or that the hostid changed (for example after booting different media).

How to diagnose it

flowchart TD
  A[zpool import fails] --> B{Exact error?}
  B -->|no such pool available| C[Devices not visible or labels unreadable]
  B -->|devices currently unavailable| D[Missing or renamed devices]
  B -->|insufficient replicas| E[Too many vdev members lost]
  B -->|unsupported version or feature| F[Feature flag mismatch]
  B -->|pool may be in use| G[Hostid mismatch or unclean export]
  C --> H[Rescan with -d /dev/disk/by-id]
  D --> H
  H --> K{Pool visible now?}
  K -->|yes| L[Import normally]
  K -->|no| M[Check labels with zdb -l then read-only rescue]
  E --> N[Restore devices or accept partial data loss]
  F --> O[Boot newer ZFS or import read-only]
  G --> P[Verify pool is not active elsewhere then -f]

1. Capture the exact error string. Run zpool import <pool> and record the message verbatim. no such pool available, insufficient replicas, and a feature complaint are three different failures.
2. Run the read-only scan. zpool import with no arguments shows what ZFS found and the state of every device it could see. A pool listed with UNAVAIL devices is a missing-device problem. A pool not listed at all is a discovery or label problem.
3. Check device visibility. Compare ls /dev/disk/by-id/ to the pool’s expected members. If devices are absent from the kernel entirely, this is hardware, cabling, HBA, or multipath, not ZFS. Check dmesg for link resets or device timeouts.
4. Check the labels. If the kernel sees the devices but the scan does not find the pool, run zdb -l on each member. All four label copies unreadable on a device means real metadata damage.
5. Rule out a feature mismatch. If the pool was created or zpool upgraded on a newer system (newer OpenZFS, another OS, or a rescue image), the running ZFS may simply be too old. Confirm the OpenZFS version on both sides.
6. For a root pool, reproduce from rescue media. Boot alternate media and try the import there. If it imports cleanly from rescue media but fails in initramfs, the problem is boot-path timing or a stale cachefile, not the pool.

Metrics and signals to monitor

Import failures are almost always preceded by monitorable signals. The pool was usually DEGRADED or accumulating vdev errors before it became unimportable.

Per-vdev error counters are in-memory and reset on export/import, so a clean counter after a failed-import event does not mean the device was healthy before it.

Fixes

Ordered from safest to most destructive. Stop at the first one that works.

Missing or renamed devices

If the scan finds the pool under /dev/disk/by-id but not the default paths, import with an explicit directory:

# Import using persistent device names
zpool import -d /dev/disk/by-id tank

This is safe and non-destructive. Going forward, pools should reference /dev/disk/by-id paths so kernel device renumbering cannot break discovery. If a device is genuinely missing, restore connectivity (cable, HBA, enclosure, multipath path) and rescan. ZFS will not import a vdev short of its redundancy minimum; there is no supported way to open a pool past “insufficient replicas” without the missing members.

Hostid mismatch or unclean export: -f only

If the scan reports the pool may be in use on another system:

# Force import past the hostid check
zpool import -f tank

-f bypasses the hostid/activity check. It does not discard any transactions and is generally safe, with one hard exception: if the pool is genuinely imported and active on another host, forcing the import here will corrupt it. In shared-storage or multihost (MMP) environments, verify the other host is down before using -f.

Read-only import for data rescue

Before touching anything transactional, try a read-only import. It writes no metadata, syncs no txgs, replays no ZIL, and bypasses some write-side feature checks, which makes it the right move for both damaged pools and feature mismatches:

# Read-only import without mounting anything
zpool import -o readonly=on -N tank
zfs mount tank/data        # mount individual datasets as needed

From here, copy data off or zfs send datasets to another pool. If read-only import works, your recovery question is answered and every further step is optional.

Transaction rewind: -F, then -FX / -T as last resorts

If normal import fails because the most recent transactions are unrecoverable, -F rewinds the pool to an earlier transaction group, discarding the last few transactions:

# Recovery mode: rewinds to an earlier txg
# DESTRUCTIVE: data from discarded transactions is permanently lost
zpool import -F tank

Run zpool import -Fn tank first if you want to see what would happen without committing to it. If -F cannot find a usable txg, -FX tries extreme measures and may leave the pool with uncorrectable checksum errors; -T <txg> targets a specific transaction group and implies -FX. Treat both as last resorts before declaring the pool lost, and prefer a read-only rescue over either when the goal is data extraction.

Missing log device: -m

If the only missing device is the SLOG:

# Import with a missing log device; recent sync transactions may be lost
zpool import -m tank

Data committed in recent transactions that only existed in the log may be lost. The pool’s main data vdevs are unaffected.

Feature flag mismatch

A pool with features enabled that the running ZFS does not support cannot be imported read-write, and you cannot downgrade a pool. Options, in order:

1. Boot or attach the pool to a system running the newer OpenZFS version. This is the correct fix.
2. If you are stuck on the older version, zpool import -o readonly=on may still work for data rescue, since read-only import skips some write-side feature checks.

This commonly bites after an OS downgrade, after booting an older rescue image, or when a pool created on a newer release is attached to an older one. Never run zpool upgrade on a pool that must remain importable by older boot environments.

Root-pool boot failure

When initramfs reports cannot import rpool: no such pool available but the pool imports fine from rescue media, the usual causes are device enumeration timing and a stale cachefile:

1. Give devices time to appear. On Debian/Ubuntu-style setups, add sleep delays in /etc/default/zfs:

# /etc/default/zfs: wait for slow devices during initramfs
ZFS_INITRD_PRE_MOUNTROOT_SLEEP='5'
ZFS_INITRD_POST_MODPROBE_SLEEP='5'

Then regenerate the initramfs: update-initramfs -u. This is the documented fix when disks are not fully addressable at the moment initramfs attempts the import.

2. Refresh the pool cachefile. A stale or missing /etc/zfs/zpool.cache makes the boot-time import scan fail. From a working boot or rescue environment:

# Rewrite the cachefile, then regenerate initramfs
zpool set cachefile=/etc/zfs/zpool.cache rpool
update-initramfs -u

3. Last-resort import recovery. The zfs_recover module parameter tells ZFS to attempt recovery from fatal errors:

# Recovery mode: attempt recovery from fatal errors
echo 1 > /sys/module/zfs/parameters/zfs_recover

This is a recovery tool, not a standing configuration; set it to get the system booted, rescue or repair, then unset it. For boot-time import control, OpenZFS 2.4.x still documents zfs_autoimport_disable; later development branches have retired the kernel option, so verify the installed release before relying on it.

Prevention

• Create and reference pools by /dev/disk/by-id. Kernel device names (/dev/sdX) are not stable across reboots, HBA changes, or enclosure swaps.
• Alert on DEGRADED and per-vdev error counters. A pool that cannot import today was usually a DEGRADED pool with climbing READ/WRITE/CKSUM counters last week. DEGRADED is a same-day ticket, not an informational state.
• Keep the cachefile and initramfs in sync. After any pool topology change on a root-on-ZFS system, verify /etc/zfs/zpool.cache is current and regenerate the initramfs.
• Gate zpool upgrade. Confirm every boot environment and rescue image that might touch the pool runs a compatible OpenZFS version before enabling new feature flags.
• Baseline pool import time. On root pools especially, track how long import takes. A rising trend (growing space maps, large ZIL replays) is early warning of boot delays that can tip into boot failures.
• Test the boot path. After any ZFS, kernel, or initramfs change on a root-on-ZFS host, reboot and confirm the pool imports before considering the change done.
• Scrub on schedule. Regular scrubs surface label and metadata damage while redundancy can still repair it. An import failure caused by damaged metadata is far easier to survive on a recently scrubbed, fully redundant pool.

How Netdata helps

Netdata shortens this incident mostly by catching the preconditions before the pool becomes unimportable:

• Pool state per pool, collected continuously, so the DEGRADED-to-UNAVAIL drift pages you while the pool is still importable, not after.
• Per-vdev READ/WRITE/CKSUM counters trended over time, distinguishing a one-time SATA reset from a device that is actively dying and will be missing at the next import.
• Scrub status and error outcomes, so metadata damage is detected and repaired while redundancy can still fix it.
• Deadman and ZFS event visibility, catching hung imports and stuck I/O that otherwise look like a silent, unbootable box.
• Correlation across layers: vdev errors plus kernel device timeouts plus a state transition, on one timeline, tells you whether you are looking at a disk, a controller, or a cabling problem before you start swapping parts.

Related guides

• ZFS checksum errors (CKSUM): the definitive signal of silent corruption
• ZFS checksum errors on multiple devices: suspect RAM or the controller, not the disks
• ZFS deadman events: hung I/O and a stalled pool sync
• ZFS cannot destroy dataset is busy: clones, holds, and mounted filesystems
• ZFS capacity planning: runway estimation before the pool fills
• ZFS deleted files but no space freed: snapshots holding the blocks