This error occurs when Docker is configured to use the ZFS storage driver but cannot find a valid ZFS dataset mounted at /var/lib/docker. The solution involves creating a dedicated ZFS dataset for Docker and properly configuring the storage driver.
The ZFS storage driver in Docker requires a dedicated ZFS dataset mounted at `/var/lib/docker` to store container images and layers. When Docker attempts to start with the ZFS driver configured but cannot locate this dataset, it fails with this error. ZFS (Zettabyte File System) is an advanced filesystem that provides features like copy-on-write, snapshots, and data integrity checking. Docker can leverage these features through its ZFS storage driver, but it requires proper setup. This error indicates that: - Docker is configured to use the ZFS storage driver (either explicitly via daemon.json or detected automatically) - No ZFS dataset is mounted at `/var/lib/docker` - Docker cannot proceed because the required ZFS infrastructure is missing This commonly occurs when: - You've installed ZFS and want to use it with Docker but haven't created the necessary dataset - Docker was previously configured for ZFS but the dataset was deleted or unmounted - The system was migrated or cloned without preserving ZFS mount configuration
First, verify what ZFS pools and datasets exist on your system:
# List all ZFS pools
zpool list
# List all ZFS datasets and their mount points
zfs list
# Check if anything is mounted at /var/lib/docker
df -h /var/lib/docker
mount | grep dockerIf you don't see any ZFS pools, you'll need to create one first. If you have pools but no dataset for Docker, proceed to create one.
Before creating the ZFS dataset, stop Docker and back up any existing data:
# Stop Docker service
sudo systemctl stop docker
sudo systemctl stop docker.socket
# Back up existing Docker data if any
if [ -d /var/lib/docker ]; then
sudo mv /var/lib/docker /var/lib/docker.bak
fiNote: If you have important containers or images, consider exporting them first using docker save before proceeding.
Create a new ZFS dataset with the mountpoint set to /var/lib/docker:
# Replace 'poolname' with your actual ZFS pool name
# Common pool names: zpool, tank, rpool, zroot
# Create the dataset with mountpoint
sudo zfs create -o mountpoint=/var/lib/docker poolname/docker
# Verify the dataset was created and mounted
zfs list poolname/docker
df -h /var/lib/dockerIf you don't have a ZFS pool yet, create one first:
# Create a pool on a dedicated disk (example: /dev/sdb)
sudo zpool create -f dockerpool /dev/sdb
# Then create the dataset
sudo zfs create -o mountpoint=/var/lib/docker dockerpool/dockerExplicitly configure Docker to use the ZFS storage driver in the daemon configuration:
# Create or edit Docker daemon configuration
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<EOF
{
"storage-driver": "zfs"
}
EOFThis ensures Docker knows to use the ZFS driver rather than attempting to auto-detect or use a different driver.
Verify that your ZFS dataset will be mounted automatically after system reboots:
# Check the mountpoint property
zfs get mountpoint poolname/docker
# Ensure canmount is set to on
zfs get canmount poolname/docker
# If canmount is off, enable it
sudo zfs set canmount=on poolname/docker
# Enable ZFS auto-mount service (systemd systems)
sudo systemctl enable zfs-mount
sudo systemctl enable zfs-import-cache
sudo systemctl enable zfs-import.targetStart Docker and verify it's using the ZFS storage driver:
# Start Docker service
sudo systemctl start docker
# Check Docker status
sudo systemctl status docker
# Verify storage driver
docker info | grep -E "Storage Driver|Data Space|Metadata Space"Expected output should show:
Storage Driver: zfsRun a test container to confirm everything is working:
# Run the hello-world test image
docker run --rm hello-world
# Pull and run a more substantial image
docker run --rm alpine cat /etc/os-release
# Check that Docker is storing data on ZFS
zfs list | grep dockerYou should see the ZFS dataset growing as you pull images.
ZFS Memory Requirements:
ZFS was originally designed for enterprise servers with substantial memory. The ZFS Adaptive Replacement Cache (ARC) can consume significant RAM. For systems with limited memory (< 8GB), consider tuning ZFS:
# Limit ZFS ARC size (example: 1GB max)
echo "options zfs zfs_arc_max=1073741824" | sudo tee /etc/modprobe.d/zfs.confCreating Separate Datasets for Better Snapshot Control:
For production environments, consider creating separate datasets for Docker root and volumes:
sudo zfs create -o mountpoint=/var/lib/docker poolname/docker-root
sudo zfs create -o mountpoint=/var/lib/docker/volumes poolname/docker-volumesThis allows independent snapshot and backup policies for containers vs. persistent data.
ZFS Deduplication Warning:
While ZFS supports deduplication, it's not recommended for Docker workloads due to high memory overhead. Keep dedup disabled:
zfs get dedup poolname/docker
# Should show: dedup offFreeBSD-Specific Notes:
On FreeBSD, you may need to enable procfs for Docker's ZFS driver to work correctly:
# Add to /etc/fstab
proc /proc procfs rw 0 0
# Mount it
mount /procAlso ensure the docker group exists in /etc/group.
Native ZFS vs FUSE:
Always use native ZFS (kernel module) rather than ZFS-FUSE. The FUSE implementation has significantly worse performance and may cause stability issues with Docker.
Overlay2 on ZFS:
Note that overlay2 storage driver is NOT supported when /var/lib/docker is on a ZFS filesystem. If your root filesystem is ZFS and you want to use Docker, you must use the ZFS storage driver.
Recovery from Corrupted State:
If Docker's ZFS state becomes corrupted, you may need to clean up orphaned datasets:
# List Docker-created datasets
zfs list -r poolname/docker
# Remove Docker data (DESTRUCTIVE)
sudo systemctl stop docker
sudo zfs destroy -r poolname/docker
sudo zfs create -o mountpoint=/var/lib/docker poolname/docker
sudo systemctl start dockerunable to configure the Docker daemon with file /etc/docker/daemon.json
How to fix 'unable to configure the Docker daemon with file daemon.json' in Docker
docker: Error response from daemon: OCI runtime create failed: container_linux.go: starting container process caused: exec: "/docker-entrypoint.sh": stat /docker-entrypoint.sh: no such file or directory
How to fix 'exec: entrypoint.sh: no such file or directory' in Docker
image operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
dockerfile parse error line 5: unknown instruction: RRUN
How to fix 'unknown instruction' Dockerfile parse error in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker