🚨 Docker Error Guide: 'error initializing graphdriver' — Fix Storage Driver Startup

Overview

This is a daemon-startup failure: the Docker service refuses to come up because it cannot initialize the storage driver that manages image and container layers under its data root. You see it in the service status or the daemon log, not from a docker run:

failed to start daemon: error initializing graphdriver: driver not supported

Common variants name the specific problem:

error initializing graphdriver: prior storage driver overlay2 failed: driver not supported
error initializing graphdriver: backing file system is unsupported for this graph driver

While this is happening, docker commands fail with Cannot connect to the Docker daemon because the daemon never finished starting.

Symptoms

• sudo systemctl start docker fails and systemctl status docker shows the daemon exiting immediately.
• Every docker CLI command returns Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
• The failure appears right after upgrading Docker, changing the kernel, editing daemon.json, or moving data-root to a new disk.
• journalctl -u docker shows error initializing graphdriver on each restart attempt.
• A previously working host stops starting Docker after /var/lib/docker was restored, copied, or placed on a different filesystem (e.g. NFS, tmpfs, ZFS).

Common Root Causes

• Storage driver mismatch — daemon.json forces storage-driver to a value that conflicts with what already exists in the data root; Docker refuses to reinterpret an overlay2 data root as, say, devicemapper.
• Unsupported backing filesystem — overlay2 requires a supported backing filesystem (ext4 or xfs with d_type=true); on an unsupported filesystem it reports backing file system is unsupported.
• xfs without ftype=1 — an XFS filesystem formatted without ftype=1 cannot back overlay2.
• Missing kernel module / feature — the overlay kernel module is not loaded or the kernel lacks the feature the driver needs.
• Data root on an incompatible mount — data-root was pointed at NFS, tmpfs, or a network volume that the chosen driver cannot use.
• Corrupt or partial data root — an interrupted upgrade, a bad rsync, or a disk error left the layer metadata inconsistent.
• Leftover state from a different driver — the data root contains subdirectories from a previously used driver, so Docker sees conflicting state.

Diagnostic Workflow

Read the full daemon error first — it almost always names the driver and the reason:

sudo journalctl -u docker --no-pager -n 40

level=error msg="failed to start daemon: error initializing graphdriver:
  backing file system is unsupported for this graph driver"

Check what the daemon is configured to use versus what exists on disk:

cat /etc/docker/daemon.json        # is storage-driver being forced?
ls /var/lib/docker                 # look for overlay2/, aufs/, devicemapper/ dirs

Identify the filesystem backing the data root and whether it supports overlay2:

df -T /var/lib/docker              # shows the filesystem type (ext4, xfs, nfs, ...)

For XFS, confirm ftype=1 (required for overlay2):

sudo xfs_info /var/lib/docker | grep ftype

naming   =version 2  bsize=4096  ascii-ci=0  ftype=1

ftype=0 means overlay2 cannot use this filesystem. Confirm the overlay kernel module is available:

lsmod | grep overlay
sudo modprobe overlay && echo "overlay loadable"

Try starting the daemon in the foreground to see the error live:

sudo dockerd --debug

Example Root Cause Analysis

After migrating Docker’s data root to a freshly attached data disk, the daemon would not start:

error initializing graphdriver: backing file system is unsupported for this graph driver

The team had set {"data-root": "/data/docker"} and formatted /data as XFS. df -T /var/lib/docker (via the symlinked path) showed xfs, and xfs_info revealed the culprit:

naming   =version 2  bsize=4096  ascii-ci=0  ftype=0

The XFS filesystem had been created without ftype=1, which overlay2 requires. The old root disk had been ext4, so the problem only surfaced after the move.

Fix: reformat the data volume with ftype=1 (XFS requires this at mkfs time — it cannot be toggled later), restore the data root onto it, and start the daemon:

sudo systemctl stop docker
sudo umount /data
sudo mkfs.xfs -f -n ftype=1 /dev/nvme1n1
sudo mount /data
sudo systemctl start docker

The daemon then initialized overlay2 cleanly. (Where reformatting is not an option, pointing data-root back to an ext4 filesystem resolves it just as well.)

Prevention Best Practices

• Format any filesystem intended to back /var/lib/docker as ext4, or XFS with mkfs.xfs -n ftype=1; verify before pointing Docker at it.
• Do not force storage-driver in daemon.json unless you are matching what already exists in the data root; let Docker auto-select overlay2 on supported systems.
• Keep the data root on local block storage; avoid NFS, tmpfs, and network volumes for /var/lib/docker.
• When moving data-root, stop the daemon, copy with rsync -aP, verify the destination filesystem type, and only then restart.
• Ensure the overlay kernel module loads at boot on hosts using overlay2.
• After a Docker or kernel upgrade, check journalctl -u docker on first start so a driver problem is caught immediately.

Quick Command Reference

# See exactly why the daemon failed to start
sudo journalctl -u docker --no-pager -n 40

# Run the daemon in the foreground to watch initialization
sudo dockerd --debug

# Show the filesystem type backing the data root
df -T /var/lib/docker

# Check XFS ftype (must be 1 for overlay2)
sudo xfs_info /var/lib/docker | grep ftype

# Confirm the overlay kernel module is available
lsmod | grep overlay
sudo modprobe overlay

# View the configured storage driver
cat /etc/docker/daemon.json
docker info --format '{{.Driver}}'   # only works once the daemon starts

Conclusion

error initializing graphdriver stops the Docker daemon before it can serve any request, so fix it at the host level: read the daemon log to get the exact reason, then reconcile the chosen storage driver with the data root’s actual contents and backing filesystem. Most cases come down to an overlay2-incompatible filesystem (XFS without ftype=1, or a network mount) or a forced storage-driver that conflicts with existing state. Put the data root on a supported local filesystem and let Docker select overlay2, and the daemon initializes cleanly.