-
@ Girino Vey!
2025-05-02 03:50:51Introduction: Don't Despair—This Can Be Fixed (But Don't Reboot Yet)
Running ZFS on a Raspberry Pi offers powerful features for home servers and personal NAS setups. But with power comes complexity, and in recent months, a quiet pitfall has emerged for Pi users who track kernel updates closely: upgrading to an unsupported kernel version breaks ZFS.
⚠️ Important Warning: If you've just upgraded your kernel and you're using ZFS, do not reboot yet. Rebooting without a working ZFS module can leave your system unbootable—even if you don't have critical partitions on ZFS. The system may hang because it tries to load the missing ZFS kernel module during boot and fails, halting the boot process.
If you're already facing a broken setup or can't boot — don't panic. This guide outlines both the worst-case scenario and the ideal recovery strategy. Whether you're locked out or preparing for a smooth upgrade, we've got you covered.
The Problem: A Kernel Update Too Far
As of ZFS version 2.2.3 (used in Debian-based Raspberry Pi OS), the filesystem supports Linux kernels up to 6.7. However, Raspberry Pi OS backports recently began shipping 6.12.x kernels. If you upgrade to 6.12 without precautions:
- ZFS will fail to compile against the new kernel
- DKMS errors will appear during package updates
- Your ZFS module will be missing after reboot
- Your Raspberry Pi may fail to boot, even without ZFS-mounted root or critical paths, simply due to systemd or boot scripts expecting the kernel module to be present
Example ZFS Compilation Error:
During package updates or installs, you'll see something like:
checking whether bdev_open_by_path() exists... configure: error: *** None of the expected "blkdev_get_by_path()" interfaces were detected. *** This may be because your kernel version is newer than what is *** supported, or you are using a patched custom kernel with *** incompatible modifications. *** *** ZFS Version: zfs-2.2.3-1~bpo12+1~rpt1 *** Compatible Kernels: 3.10 - 6.7This error means ZFS cannot build its kernel module against Linux 6.12.x, making it unusable.
Why This Happens: The Version Trap
The key problem is that ZFS 2.2.3 remains installed even after a kernel upgrade, and it doesn't get upgraded automatically during
apt upgrade. Since ZFS 2.2.3 only supports up to kernel 6.7, it fails to compile against 6.12.x.However, if you remove and then reinstall ZFS, the package manager installs ZFS 2.3.1, which does support Linux kernel 6.12.x. This version transition is what resolves the issue — but only if you explicitly purge and reinstall ZFS.
Worst Case: The System That Wouldn’t Boot
After upgrading the kernel and rebooting, the system failed to boot properly. It showed errors like:
cannot open access to console, the root account is locked
Although the system did not have critical filesystems on ZFS, the boot process still stalled because system services attempted to load the ZFS kernel module, which was no longer available. This resulted in an unrecoverable boot failure.
The only way forward was to reformat and reinstall Raspberry Pi OS. However, the default Raspberry Pi OS image still comes with a 6.6.x kernel, which is incompatible with ZFS 2.3.1 and newer kernels unless upgraded. Therefore, the recovery process requires one crucial step:
- First, perform a full system upgrade:
sudo apt update && sudo apt full-upgradeThis brings the kernel up to 6.12.x.
- Then, reinstall ZFS:
sudo apt install zfs-dkms zfsutils-linuxOnce this is complete, your system will be running kernel 6.12 with ZFS 2.3.1, and you can safely import your pools and resume operations.
Best Case Recovery: Clean Cut, Clean Upgrade
For users who can still log into their system, here's the cleanest and safest sequence to move forward:
- Stop all services using ZFS, including Docker, NFS, Samba, backup tools, etc.
- Export all ZFS pools:
sudo zpool export -a3. Disable swap if it lives on a ZFS vdev:sudo swapoff /dev/sdXn4. Purge ZFS packages:sudo apt purge zfsutils-linux zfs-dkms zfs-zed sudo rm -rf /usr/src/zfs* /var/lib/dkms/zfs5. Update the kernel to the desired version:sudo apt update && sudo apt full-upgrade6. Reboot into the new kernel:sudo reboot7. Reinstall ZFS:sudo apt install zfs-dkms zfsutils-linux8. Import your pool(s):sudo zpool import poolname9. Restart services that depend on ZFS.
Final Notes: Prevention Is Better Than Recovery
To avoid this issue in the future:
- Hold your current working kernel version:
sudo apt-mark hold linux-image-rpi-v8 linux-headers-rpi-v8* Or track ZFS GitHub for kernel compatibility before upgrading * Or test upgrades on a second Pi or cloned SD card before rolling them out to production
Conclusion: A Solvable Trap
ZFS on the Raspberry Pi remains a powerful option, but it demands careful version tracking. If you upgrade responsibly, or recover cleanly as described above, you can continue benefiting from advanced features like snapshots, send/receive, and compression even on this tiny powerhouse.
Don’t let a kernel update ruin your storage plans—with preparation, the Pi + ZFS combo can remain stable and strong.