How to fix Error starting daemon: error initializing graphdriver: could not locate zfs dataset in Docker

DockerINTERMEDIATEHIGHUpdated Dec 6, 2025· 132 views

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.

Quick fix

Fixes Error starting daemon: error initializing graphdriver: could not locate zfs dataset

# 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 docker
  1. Check current ZFS pools and datasets
  2. Stop Docker and clean up existing data
  3. Create a ZFS dataset for Docker
  4. Configure Docker to use the ZFS storage driver
docker — error
# 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 docker
Error starting daemon: error initializing graphdriver: could not locate zfs dataset

What this error means

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

Typical symptoms

  • Docker daemon fails to start with 'could not locate zfs dataset' error
  • systemctl start docker fails immediately after ZFS installation
  • Docker worked before ZFS was installed but fails after enabling ZFS driver
  • Error message mentions 'error initializing graphdriver' with ZFS
  • journalctl shows Docker service failing during startup
  • docker info command cannot run because daemon is not responding

Common causes

  1. No ZFS dataset is mounted at /var/lib/docker
  2. Docker configured to use ZFS driver but ZFS pool/dataset not created
  3. ZFS dataset exists but is not mounted at the correct location
  4. ZFS pool was imported but datasets were not auto-mounted
  5. /var/lib/docker directory exists but is not on a ZFS filesystem
  6. Previous Docker installation left residual data preventing ZFS detection
  7. System reboot caused ZFS datasets to not mount automatically

How to fix "Error starting daemon: error initializing graphdriver: could not locate zfs dataset"

1Check current ZFS pools and datasets

First, verify what ZFS pools and datasets exist on your system:

bash
# 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 docker

If 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.

2Stop Docker and clean up existing data

Before creating the ZFS dataset, stop Docker and back up any existing data:

bash
# 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
fi

Note: If you have important containers or images, consider exporting them first using docker save before proceeding.

3Create a ZFS dataset for Docker

Create a new ZFS dataset with the mountpoint set to /var/lib/docker:

bash
# 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/docker

If you don't have a ZFS pool yet, create one first:

bash
# 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/docker
4Configure Docker to use the ZFS storage driver

Explicitly configure Docker to use the ZFS storage driver in the daemon configuration:

bash
# Create or edit Docker daemon configuration
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<EOF
{
  "storage-driver": "zfs"
}
EOF

This ensures Docker knows to use the ZFS driver rather than attempting to auto-detect or use a different driver.

5Ensure the ZFS dataset mounts on boot

Verify that your ZFS dataset will be mounted automatically after system reboots:

bash
# 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.target
6Start Docker and verify configuration

Start Docker and verify it's using the ZFS storage driver:

bash
# 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:

bash
Storage Driver: zfs
7Test Docker functionality

Run a test container to confirm everything is working:

bash
# 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 docker

You should see the ZFS dataset growing as you pull images.

Advanced notes

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:

bash
# Limit ZFS ARC size (example: 1GB max)
echo "options zfs zfs_arc_max=1073741824" | sudo tee /etc/modprobe.d/zfs.conf

Creating Separate Datasets for Better Snapshot Control:
For production environments, consider creating separate datasets for Docker root and volumes:

bash
sudo zfs create -o mountpoint=/var/lib/docker poolname/docker-root
sudo zfs create -o mountpoint=/var/lib/docker/volumes poolname/docker-volumes

This 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:

bash
zfs get dedup poolname/docker
# Should show: dedup off

FreeBSD-Specific Notes:
On FreeBSD, you may need to enable procfs for Docker's ZFS driver to work correctly:

bash
# Add to /etc/fstab
proc /proc procfs rw 0 0

# Mount it
mount /proc

Also 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:

bash
# 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 docker

Frequently asked questions

What does "Error starting daemon: error initializing graphdriver: could not locat" mean?
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.
How do I fix "Error starting daemon: error initializing graphdriver: could not locat"?
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.
What causes "Error starting daemon: error initializing graphdriver: could not locat"?
No ZFS dataset is mounted at /var/lib/docker Docker configured to use ZFS driver but ZFS pool/dataset not created ZFS dataset exists but is not mounted at the correct location
Is the "Error starting daemon: error initializing graphdriver: could not locat" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading