Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Docker will not start with the overlay2 storage driver: no such device

Errorfailed to mount overlay: no such device storage-driver=overlay2

Short answer

overlay2 needs a kernel that supports overlayfs and a backing filesystem that can carry it. Run docker info to see what the daemon picked, then check the kernel version, whether /var/lib/docker is xfs without d_type, or on a filesystem without extended attributes. The fix depends on which of the three it is.

  • Applies to Docker Engine 28, Ubuntu 24.04, RHEL 9
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the machine which kernel it runs, which filesystem holds /var/lib/docker and whether xfs has ftype=1.

    uname -r
    df -T /var/lib/docker
    sudo xfs_info /var/lib/docker | grep ftype
  2. 2Match what you see, then jump to its fix

    1. 1uname -r shows a kernel below 4.0 (or below 3.10.0-514 on RHEL and CentOS)The kernel is too old for overlay2Fix
    2. 2xfs_info shows ftype=0/var/lib/docker is on xfs created without ftype=1Fix
    3. 3/var/lib/docker sits on NFS or on another filesystem without extended attributes or valid d_typeThe backing filesystem cannot hold overlayfs upper layersFix

What does the error look like?

  • failed to mount overlay: no such device storage-driver=overlay2

Cause 1 of 3

The kernel is too old for overlay2

1Check

Docker documents Linux kernel 4.0 or later for overlay2, and 3.10.0-514 or later on RHEL and CentOS.

uname -r

2Fix

Install a newer kernel from your distribution's repositories and reboot into it. Then confirm the version again.

sudo reboot
# after the reboot
uname -r

3Verify

The daemon starts and docker info shows overlay2.

sudo systemctl restart docker
docker info | grep -E "Storage Driver|Backing Filesystem|Supports d_type"

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

/var/lib/docker is on xfs created without ftype=1

1Check

On xfs, Docker supports overlay2 only when d_type is on, which xfs_info reports as ftype=1.

sudo xfs_info /var/lib/docker | grep ftype

2Fix

Back up what you need, format a new xfs filesystem with ftype=1, mount it on /var/lib/docker and add it to /etc/fstab. The device name below is an example.

sudo systemctl stop docker
sudo mkfs.xfs -n ftype=1 /dev/sdb1

3Verify

docker info reports d_type as supported.

sudo systemctl start docker
docker info | grep "Supports d_type"

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

The backing filesystem cannot hold overlayfs upper layers

1Check

The kernel documents that the upper layer must support trusted.* or user.* extended attributes and must return a valid d_type. It names NFS as unsuitable.

df -T /var/lib/docker
findmnt -T /var/lib/docker

2Fix

Move the Docker data directory to a local ext4 or xfs disk, or mount a suitable filesystem on /var/lib/docker.

sudo systemctl stop docker
# mount a local ext4/xfs filesystem on /var/lib/docker, add it to /etc/fstab
sudo systemctl start docker

3Verify

docker info shows overlay2 on a supported backing filesystem.

docker info | grep -E 'Storage Driver|Backing Filesystem'

Confirmed by docs.kernel.org

Did this fix it?

How do I stop it coming back?

  • Put /var/lib/docker on a local ext4 or xfs (ftype=1) disk when you design the server.
  • Read docker info after every install or kernel change.
  • Back up or push images before you reformat or move /var/lib/docker.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.