Fix Docker overlayfs does not support file handles on ZFS

5 August 2026

Tags

When your Proxmox host uses ZFS, shifting Docker from using the restricted host kernel overlay system to using a User-Space filesystem (fuse-overlayfs) bypasses the file-handle restriction.

Step 1: Enable FUSE on the Proxmox Host

  1. Go to the Proxmox Web GUI.
  2. Select your Debian LXC container -> Options -> Features.
  3. Click Edit, check the box for fuse, and save.
  4. Reboot the LXC container to apply this option.

Step 2: Install and Configure FUSE inside the LXC

  1. Open the terminal/console of your Debian LXC container.

  2. Install the fuse-overlayfs binary:

    apt update && apt install -y fuse-overlayfs

  3. Tell Docker to explicitly use this driver by creating or editing the /etc/docker/daemon.json configuration file:

    nano /etc/docker/daemon.json

  4. Paste the following configuration into the file:

    {
  "storage-driver": "fuse-overlayfs"
}

  5. Save the file (Ctrl+O, Enter, then Ctrl+X) and restart the Docker service:

    systemctl restart docker

Related blog posts

Proxmox + Alpine + Docker

Install Docker on Alpine in Proxmox

27 February 2026
Compared to Debian or Ubuntu container images, Alpine Linux uses one-tenth the space and 60% less RAM. It has minimal packages installed by default which minimizes the attack surface. That makes Alpine an ideal OS for both a Docker host and simple containers. Installing Docker in an Alpine Linux container on Proxmox is really as simple as running a few commands.
Overview page on an Alpine Linux container on a Proxmox host

Install Alpine Linux in a Proxmox container

4 February 2026
Alpine Linux is a lightweight, security-focused distribution that uses musl, libc, and busybox by default. It is an excellent choice for Proxmox LXC containers when you want minimal resource usage, fast boot times, and a small disk footprint. Choose Alpine for running services like Docker hosts, monitoring tools, or simple servers inside Proxmox.