|

LXD Snap and ZFS: Fixing the “Required tool zpool is missing” Error

ByPieter Bakker

If you run LXD via snap on Ubuntu and use ZFS as your storage backend, chances are you have encountered this frustrating error at least once:

Error: Required tool "zpool" is missing. The snap does not contain ZFS tools
matching the module version ("2.1.5-1ubuntu6~22.04.6"). Consider installing
ZFS tools in the host and use 'snap set lxd zfs.external=true'

The container refuses to start, your workload is stuck, and the error message is not exactly self-explanatory. Let’s break down what is happening and how to fix it permanently.

Why This Happens

The LXD snap bundles its own copy of the ZFS userspace tools (zpool, zfs). These bundled tools need to match the version of the ZFS kernel module that is loaded on the host. When the versions diverge, the snap refuses to use its own tools and throws the error above.

The most common triggers are:

A kernel update was installed, but the system has not been rebooted yet. The running kernel still has the old ZFS module loaded, while the snap expects the newer version.

The zfsutils-linux package on the host was updated independently, causing the kernel module to be rebuilt for a different version than what the snap bundles.

The snap itself was refreshed to a version that ships different ZFS tools than the currently loaded kernel module.

Quick Fix: Use External ZFS Tools

The fastest way to resolve this is to tell the LXD snap to use the host’s ZFS tools instead of its own bundled copy:

apt install zfsutils-linux
snap set lxd zfs.external=true
systemctl restart snap.lxd.daemon

This tells the snap to look for zpool and zfs in the host system’s PATH rather than using its internal binaries. As long as the host’s zfsutils-linux package matches the running kernel module, the version mismatch disappears.

You can verify everything lines up:

# Check the loaded kernel module version
modinfo zfs | grep ^version

# Check the userspace tools version
zpool version

Both should report the same version string. If they do not, a reboot will align them.

Alternative: Just Reboot

If the mismatch was triggered by a kernel update that has not been applied yet, the simplest solution is a reboot:

reboot

After the reboot, the new kernel loads the matching ZFS module, and the snap’s bundled tools will match again. This is the right approach when you prefer to keep using the snap’s internal ZFS tools.

The Better Long Term Solution: Move to Incus

If you are still running LXD, this recurring version mismatch is one more reason to consider migrating to Incus. After Canonical moved LXD into a CLA and commercial licensing model, the Linux Containers community forked it into Incus, which is available as a standard system package on Debian and Ubuntu.

Incus uses the system’s native ZFS tools directly. There is no snap isolation layer, no bundled binaries, and no version mismatch problem. When your kernel and zfsutils-linux are in sync (which your package manager handles automatically), everything just works.

The migration from LXD to Incus is well documented and straightforward for most setups. Once migrated, you can remove the LXD snap entirely and eliminate this class of issue for good.

Summary

The “Required tool zpool is missing” error comes down to a version mismatch between the ZFS kernel module and the ZFS userspace tools bundled inside the LXD snap. Setting zfs.external=true is the quickest fix. A reboot resolves it when a pending kernel update is the cause. Moving to Incus avoids the problem entirely by removing the snap layer from the equation.

Similar Posts