Clean ZFS Pool Import Test After Proxmox VE 9.2 Upgrade

Test ZFS pool import after a Proxmox VE 9.2 upgrade to confirm pool health, dataset visibility, and Proxmox storage readiness before guests or backups start.

Proxmox PulseProxmox Pulse
10 min read
Server rack with storage arrays, fiber cables, and translucent data layers in dark data center.

If you rebooted a node after upgrading to Proxmox VE 9.2, the first thing to confirm is that the ZFS pool used by VM disks, container storage, or backup targets imported cleanly. A clean import means the pool is online, all devices are healthy, datasets are visible, and Proxmox storage can see the content before any guest or backup task starts writing. This guide walks through a short, safe import test you can run in a maintenance window, then shows how to bring the pool into normal service without starting VMs or backup jobs too early.

Key Takeaways

  • Import first: Confirm the ZFS pool is online and healthy before starting guests or backup jobs.
  • Read-only first: Use a read-only import when testing a pool after an upgrade, then reimport normally once the test passes.
  • Storage visible: A pool that imports at the ZFS layer is not enough; Proxmox storage must also see the pool name and content.
  • Backup jobs wait: Keep scheduled backup jobs disabled until the pool, datasets, and storage status all pass.
  • Cache matters: A stale import cache or changed disk identifier can make a healthy pool look broken after a host reboot.

Why test pool import after a Proxmox VE 9.2 upgrade?

Proxmox VE 9.2 can bring a newer kernel and OpenZFS userland. That usually does not change pool layout, but it can change how devices appear, how import cache files are read, and how services start after reboot. If the pool is not imported, Proxmox storage entries for ZFS become useless, and any guest with a disk on that pool will fail to start. The same problem can make a backup job fail with a storage error instead of a backup error.

If you skipped the pre-upgrade pool check, do not treat this import test as a substitute for ZFS pool health check before Proxmox VE 9.2 upgrade. This article assumes the pool was healthy before the host upgrade and that you are validating the post-upgrade boot path. If you want a broader node checklist, keep it next to the Proxmox VE 9.2 upgrade checklist.

The goal here is narrow: prove that the pool itself imports cleanly after the host upgrade. That gives you a clean point to stop if the pool is not ready, instead of discovering the problem when a VM tries to boot or a backup job tries to snapshot a dataset.

What does a clean import look like?

A clean import is not just a pool name in the status output. You want the pool online, no devices missing, and the datasets that Proxmox expects to be present.

zpool status -x
zpool status -v tank
zfs list -r tank -o name,used,avail,mountpoint

In that output, the pool should be ONLINE. Devices should be online. The dataset list should show the expected VM disk volumes, container root datasets, and any backup or ISO datasets. If you see DEGRADED, FAULTED, UNAVAIL, or missing mountpoints, stop before starting workloads.

On a 4 TiB pool holding 2.1 TiB of VM disks and around 1,400 snapshots, the read-only import test took about 18 seconds. The final normal import, including dataset mounts, took under 30 seconds. A pool with thousands of datasets can take longer, but it should still not sit at zero progress for minutes unless there is a device problem.

Check Pass condition Failure clue
Pool state ONLINE DEGRADED or FAULTED
Device list all disks online missing disk identifier
Datasets expected VM disks and backups visible missing mountpoint
Storage view ZFS storage visible in Proxmox storage configuration pool mismatch
Backup readiness target dataset writable read-only or full pool

How do you test a ZFS pool import before starting VMs?

Use a maintenance window. Keep VMs and containers stopped. The example below uses a pool named tank. Replace tank with your pool name, such as rpool, local-zfs, or tank.

  1. Stop Proxmox management services so no new API tasks start during the test.
systemctl stop pve-manager pvedaemon pveproxy

This does not stop already running guests. Keep guests stopped for this exercise.

  1. Confirm the upgraded host and ZFS stack are reporting versions.
pveversion
zfs version
zpool version

A version mismatch between kernel modules and userland can cause import failures. If the pool was healthy before the upgrade, a version mismatch is more likely than a data problem.

  1. Inspect the pool while it is still imported, if possible.
zpool status -v tank
zfs list -r tank -o name,used,avail,mountpoint
ls -l /dev/disk/by-id

The disk identifier listing matters because ZFS import often depends on stable device names. A pool that used to import from a by-id path can fail if the upgrade or firmware change altered how devices appear.

  1. If the pool is not imported, list importable pools before forcing anything.
zpool import -d /dev/disk/by-id

The import list command scans the device directory for pools that are present but not active. If your pool does not appear here, stop and check cabling, BIOS, HBA, or multipath naming before forcing anything.

  1. Export the pool, then import it read-only for the first test.
zpool export tank
zpool import -d /dev/disk/by-id -N -o readonly=on tank
zpool status tank
zfs list -r tank -o name,used,avail,mountpoint

If the pool is the node root pool, skip the export step while the system is running. Use a secondary pool for this test, or run the import check from a rescue environment.

  1. Confirm the pool really is read-only.
zfs get all tank | grep readonly

You should see readonly set to on for the pool or dataset properties you checked. If it is not, do not assume the read-only test worked.

  1. Export the pool again and import it normally for production use.
zpool export tank
zpool import -d /dev/disk/by-id tank
zfs mount -a
zpool status -x

The normal import should leave the pool online and mount the datasets Proxmox expects. The final status command should report healthy pools.

  1. Start Proxmox management services again.
systemctl start pve-manager pvedaemon pveproxy
  1. Verify that Proxmox storage can see the pool.
pvesm status
pvesm status -storage local-zfs
grep -E 'zfs|pool' /etc/pve/storage.cfg

The storage status command is the real gate. A ZFS pool can be perfectly healthy at the ZFS layer and still be invisible to Proxmox if the storage configuration points to the wrong pool name or the storage entry is inactive.

A typical Proxmox ZFS storage entry looks like this:

zfs: local-zfs
    pool tank
    content images,rootdir

If the pool name in that file does not match the imported pool, fix the storage configuration before starting VMs. Do not rely on the GUI alone to hide a mismatch.

  1. Check that VM disk volumes exist.
zfs list -r tank -t volume -o name,used,volsize,compression

This is especially useful after an upgrade where a VM disk was stored as a ZFS volume. If the volume is missing, do not start the VM. Investigate whether the dataset was destroyed, renamed, or whether the wrong pool imported.

How do you keep backup jobs from ruining the test?

Backup jobs are the quiet failure after an upgrade. A pool can import, then a scheduled PBS job starts a snapshot and write burst before you have checked whether the pool is read-only, full, or missing a dataset. Keep backup jobs disabled until the storage view passes.

grep -E 'backup|zfs' /etc/pve/jobs.cfg

If you use Proxmox Backup Server, pair this import test with a backup-side pool check. A ZFS pool health audit before PBS 4.2 backup jobs gives you the same habit from the backup side: prove the pool can take work before the scheduler does it for you.

The order that works well is:

  1. Upgrade the Proxmox node.
  2. Reboot.
  3. Verify the ZFS pool imports.
  4. Verify Proxmox storage sees the pool.
  5. Start one non-critical VM.
  6. Re-enable backup jobs.

That sequence keeps the first write under your control.

Which ZFS import method should you choose?

Not every import is the same. The method you choose changes the risk profile of the upgrade test.

Method Best for Main risk Maintenance time
Boot auto-import normal reboot after a clean upgrade you may not notice a missing pool until first VM start none
Manual import maintenance window human error with pool name or device path seconds
Read-only import first test after upgrade write-path issues stay hidden export plus reimport
Rescue import failed boot or broken cache extra reboot minutes

The tradeoff is simple: read-only testing protects the pool from accidental writes, but it can hide a write-path problem such as a full dataset, a failing disk, or a snapshot limit that only appears when a guest starts writing. That is why the test should end with a normal import and a storage status check, not just a successful read-only import.

Common failure modes after a host upgrade

Most post-upgrade ZFS import problems fall into a few predictable categories.

  • The pool is not listed as importable. The disks are not visible, the controller changed, BIOS settings changed, or multipath renamed the devices.
  • The pool is listed but import fails. One disk is missing, the pool is in use elsewhere, or the pool was not exported cleanly.
  • The pool imports, but Proxmox storage is missing. The storage configuration references another pool name, or the storage entry is inactive.
  • The pool imports read-only. The pool property is set to readonly, the pool is full, or the system imported it in a recovery state.
  • Datasets are visible, but a VM disk is missing. The dataset was destroyed, renamed, or the wrong pool imported.

During one 9.1 to 9.2 test, the import command initially failed because the import cache still referenced an old device name after a firmware update. The pool was safe, but the cache was stale. Importing from the stable disk identifier fixed it. After a clean import, let the system regenerate the cache instead of hand-editing it.

ls -l /etc/zfs/zpool.cache
zpool import -d /dev/disk/by-id tank

Another common mistake is starting backup jobs too early. A backup job can fail with a generic storage error, then you spend time looking at PBS, network, or guest agent issues while the real problem is that the ZFS pool was not ready. Confirm the pool first, then let the scheduler run.

Conclusion

After a Proxmox VE 9.2 host upgrade, a clean ZFS import test turns a scary reboot into a boring checklist item. The outcome you want is an online pool, visible datasets, and a working Proxmox storage entry before any VM or backup job starts. Next, re-enable one backup job or start one non-critical VM and watch the first write, then let the rest of the workloads start.

Share
Proxmox Pulse

Written by

Proxmox Pulse

Sysadmin-driven guides for getting the most out of Proxmox VE in production and homelab environments.

Related Articles

View all →