$ guides / zfs / zfs-slow-pool-import ▌

Operations Guides

ZFS slow pool import: space-map loading, ZIL replay, and import hangs

You ran zpool import tank (or the system is booting root-on-ZFS) and nothing has happened for ten minutes. No output, no prompt, no error. The instinct is that the import has hung and to reach for a reboot or a forced import. Both are usually wrong.

A slow import is usually ZFS replaying state it must replay before the pool is safe to use: loading space maps for metaslabs, replaying the ZIL after an unclean shutdown, and working through pending async destroy work left by deleted datasets or snapshots. On a large, fragmented, heavily snapshotted pool this can legitimately take minutes to, in extreme cases, an hour or more.

The operational problem is telling “slow but making progress” from “genuinely stuck.” A genuine hang during import is almost always a deadman or hardware issue, not normal replay, and the response is completely different. This article covers the checks that distinguish the two and the levers that actually shorten import time.

What this means

Import is not a single operation. ZFS walks a sequence of phases: locate and validate vdevs, load the pool configuration and metadata, read space maps and load metaslabs so the allocator knows what is free, replay the ZIL if the pool was not cleanly exported, and process any pending async destroy backlog (the freeing property). Only then does it mount datasets, which itself can be slow on pools with thousands of datasets or snapshots.

Each phase scales with a different property. Space-map loading scales with fragmentation and metaslab count. ZIL replay scales with the synchronous write backlog at the moment of the crash. Async destroy scales with blocks waiting to be freed. Dataset mounting scales with dataset and snapshot count. A pool can be fast through four phases and sit in the fifth for twenty minutes.

On root-on-ZFS this directly blocks boot, which is why import time deserves a baseline and a trend, not a shrug during incidents.

flowchart TD
    A[Import appears stuck] --> B{dbgmsg advancing?}
    B -->|new lines, phases progressing| C[Normal replay: wait]
    C --> D{Which phase is slow?}
    D --> E[Space-map / metaslab load]
    D --> F[ZIL replay]
    D --> G[Async destroy backlog]
    D --> H[Dataset mounting]
    B -->|no progress for minutes| I{Deadman events or hung task warnings in dmesg?}
    I -->|yes| J[Genuine hang: hardware or driver path]
    I -->|no, but zero progress| K[Check memory pressure, device health]

Common causes

Cause	What it looks like	First thing to check
Fragmented space maps / many metaslabs to load	Steady disk read activity during import; slow on old, full, fragmented pools	`zpool list -o name,cap,frag` from a prior import; dbgmsg showing metaslab load activity
ZIL replay after unclean shutdown	Import slow only after crash or power loss; clean export imports fast	Was the last shutdown unclean? dbgmsg for ZIL replay phase
Async destroy backlog	Large `freeing` value; import slow after mass snapshot or zvol deletion	`zpool get freeing <pool>` (on a read-only import if needed)
Many datasets/snapshots	Import completes, then the mount phase drags	`zpool import -N` to isolate import from mount
L2ARC index rebuild	Slower import with persistent L2ARC (OpenZFS 2.0+)	Does the pool have cache vdevs: `zpool status`
Memory pressure or OOM during import	Import stalls, OOM killer messages, system thrashing	`dmesg` for OOM kills; available memory
Genuine hang (deadman, device fault)	Zero progress, hung task warnings, all zfs commands block	`zpool events -v`, `dmesg`, device health
Corrupted metadata	Import panics or loops on a specific phase	dbgmsg tail; consider read-only or `-T <txg>` recovery

Quick checks

All of these are read-only and safe to run from a second shell while an import is in progress.

# Watch what phase the import is in (Linux)
tail -f /proc/spl/kstat/zfs/dbgmsg

dbgmsg is the single most useful tool here. It logs internal ZFS state transitions: spa_load activity, log spacemap reads, metaslab loads, ZIL replay. If new lines keep appearing, the import is working. If the buffer has been silent for ten minutes, you have a different problem.

# Check for deadman events and other ZFS error reports
zpool events -v | grep -i -E "deadman|io_failure|probe_failure"

# Check for kernel-level hung task or device errors
dmesg | grep -i -E "hung task|blocked for more than|ata|sas|reset|timeout|oom"

Deadman events mean an I/O or pool sync has been stuck for minutes (zfs_deadman_ziotime_ms defaults to 300000, zfs_deadman_synctime_ms to 600000). Hung task warnings in dmesg point the same direction. Either one moves you out of “slow replay” territory and into hardware or driver territory.

# Check async reclaim backlog once you can talk to the pool
zpool get freeing <pool>

# Check pool fill and fragmentation
zpool list -o name,size,alloc,free,cap,frag

A large freeing value means blocks from destroyed datasets or snapshots are still being reclaimed, and import will process that backlog.

# Count datasets and snapshots (after import, or on a read-only import)
zfs list -r <pool> | wc -l
zfs list -t snapshot -r <pool> | wc -l

Tens of thousands of these explains a slow mount phase even when import itself was quick.

# Check whether the log_spacemap feature is active
zpool get feature@log_spacemap <pool>

How to diagnose it

Establish that the import is alive. Tail /proc/spl/kstat/zfs/dbgmsg. New entries every few seconds, even cryptic ones, mean progress. Note which phase names repeat; that is your bottleneck.
Rule out the genuine hang. Run zpool events -v and check dmesg for deadman, hung task, SATA/SAS reset, or timeout messages. Check whether zpool/zfs commands on already-imported pools still respond. If everything ZFS-related blocks, suspect a device or controller, not replay.
Rule out memory pressure. Check dmesg for OOM kills and watch available memory during the import. There are operator reports of imports OOMing on large pools with limited RAM. If the import consumes memory without bound, a read-only import (step 5) typically completes with far less.
Identify the slow phase from dbgmsg and pool shape. Heavy metaslab/space-map activity on a pool you know is >85% full and fragmented: space-map loading. Slow only after a crash: ZIL replay. Recent mass deletion of zvols or snapshots: async destroy. Import finishes but mounts crawl: dataset count.
If you need the data now, do a read-only import. zpool import -o readonly=on -N <pool> imports the pool without write access, so it does not replay ZIL records or complete write-backed async-destroy work; -N also skips mounting file systems. This is the canonical recovery path when a read-write import hangs or takes too long. It writes nothing to the pool. Verify the data is there, then plan the real import.
Compare against your baseline. If you trend import duration (you should, especially for root-on-ZFS), you know whether 12 minutes is normal for this pool or a 10x anomaly. A genuine hang is far more likely well past your established baseline.
If the import panics or loops on corruption, stop retrying read-write. Recovery options include read-only import with -f, or importing to an earlier transaction group with -T <txg>. Both are recovery procedures: -T rewinds pool state and discards everything after that TXG, so copy what you can reach read-only before attempting anything that writes.

Metrics and signals to monitor

Signal	Why it matters	Warning sign
Pool import duration (baseline and trend)	The only way to distinguish “slow for this pool” from “stuck”; directly blocks boot on root-on-ZFS	Sudden multi-x increase versus trend
`zpool get freeing` backlog	Pending async destroy work that import must process	Large value after mass deletions; rebooting into it blind
Pool capacity and fragmentation (`cap`, `frag`)	Drives space-map size and metaslab load cost	cap > 85% with frag > 50% on write-heavy pools
Dataset and snapshot count	Drives mount-phase time after import	Unbounded snapshot growth from automation
Deadman events (`zpool events`)	Distinguishes genuine hung I/O from slow replay	Any deadman event
dbgmsg progress during import	Ground truth for which phase is consuming time	Silence for many minutes mid-import
L2ARC presence	Persistent L2ARC rebuilds its index on import, adding time	Slow import appearing after adding cache vdevs

Fixes

There is no single “make import fast” switch. You fix the cause, or you accept the time and plan around it.

Shorten ZIL replay cost

ZIL replay only happens after an unclean shutdown, and its cost scales with the synchronous write backlog at the moment of the crash. You cannot tune replay itself away on current releases. What you can do: keep clean shutdowns clean (let the export finish; do not cut power on a syncing pool), and size your SLOG correctly so the in-flight ZIL is bounded by design rather than by accident. Upstream PR #17044 proposed pre-loading the ARC during replay, but it was closed unmerged on 2025-06-19 and is therefore not in tagged OpenZFS releases.

Reduce space-map and metaslab load cost

Space-map load time is a symptom of pool shape: high capacity, high fragmentation, many metaslabs. The durable fixes are the same ones that fix write performance: keep capacity under ~80%, keep fragmentation from trending up, and expand or recreate the pool (send/recv to fresh vdevs) when fragmentation is severe. If the pool was created before OpenZFS 2.0, check zpool get feature@log_spacemap; enabling log-structured spacemaps reduces spacemap write cost going forward, though load time on import is still proportional to what has accumulated. OpenZFS 2.1.6 specifically included improvements to log spacemap load time, so if you are on an older release with this feature active, upgrading the modules is one of the few interventions that directly shortens import.

Drain the async destroy backlog before rebooting

If zpool get freeing shows a large backlog and a maintenance reboot is coming, let the reclaim finish first, or accept that you are choosing a slow import. Destroying thousands of zvols and immediately rebooting is the classic way to create a one-hour import. The zfs_async_block_max_blocks module parameter bounds async-destroy work; its default is unlimited, so check the module documentation and the host’s current value before relying on it. The safe, version-independent lever remains the read-only import.

Speed up device discovery and mounting

On pools with many devices, importing with a cachefile (zpool import -c /etc/zfs/zpool.cache) avoids rescanning every device on the system. The tradeoff: the cachefile goes stale if pools or devices change between boots, so regenerate it as part of pool changes. If the mount phase is the slow part (thousands of datasets), use zpool import -N and mount selectively, or reduce dataset and snapshot count. Snapshot sprawl has a real import-time cost, not just a capacity cost.

When it is a genuine hang

If deadman events fire or dmesg shows device timeouts during import, stop treating this as a ZFS tuning problem. Check cabling, controller state, and per-device health. A single device that takes minutes to fail an I/O can stall the entire import pipeline. If the pool imports fine with one suspect device physically removed and redundancy intact, you have your answer. See the related guide on deadman events for that path.

Prevention

Baseline import time per pool and trend it. Without a baseline, every slow import is a guessing game. Record it on every boot and every manual import.
Watch the freeing backlog as part of snapshot lifecycle management. Mass deletions followed by reboots are self-inflicted slow imports.
Manage capacity and fragmentation together. A pool kept under 80% capacity with fragmentation under 30% imports noticeably faster than the same pool at 90% and 60%.
Keep OpenZFS current within your support window. Import-time improvements (log spacemap load, and eventually ZIL replay priming) arrive through module upgrades, not configuration.
On root-on-ZFS, test boot time after major pool changes. A full pool plus a large snapshot destroy is exactly the combination that turns a 30-second boot into a 20-minute one.
Keep shutdowns clean. Most ZIL replay pain is avoidable by letting exports and TXG syncs complete.

How Netdata helps

Netdata collects ZFS pool capacity, fragmentation, and the freeing backlog over time, so you can see a slow-import setup forming weeks before the reboot that exposes it.
Per-vdev I/O utilization and latency during import show whether the disks are actively being read (replay in progress) or idle (something is stuck).
Deadman and other ZFS error events surface alongside kernel logs, so “slow replay” versus “hung I/O” is a correlation you can make from one dashboard instead of three shells.
Trending boot-time signals on root-on-ZFS hosts turns “the server took forever to come back” into a measurable regression you can bisect.
Snapshot count and snapshot space trends tie directly into the mount-phase and async-destroy causes, letting you catch automation that creates snapshots faster than it prunes them.