🚨 Docker Error Guide: 'failed to mount overlay: invalid argument' overlay2 Storage Failures

Exact Error Message

The overlay2 storage driver fails to assemble a container’s layered filesystem and the daemon refuses to start the container:

error creating overlay mount to /var/lib/docker/overlay2/3f9a.../merged: failed to mount overlay: invalid argument

Related variants surface during container start or daemon boot:

error creating overlay mount to /var/lib/docker/overlay2/.../merged: too many levels of symbolic links

[graphdriver] prior storage driver overlay2 failed: driver not supported: backing filesystem does not support overlay

overlay2: the backing xfs filesystem is formatted without d_type support, which leads to incorrect behavior. Reformat the filesystem with ftype=1 to enable d_type support.

What It Means

Docker’s default overlay2 driver stacks read-only image layers and a writable layer into a single merged view using the kernel’s OverlayFS. To do that correctly, the backing filesystem must support d_type — the ability to report a directory entry’s type. The classic failure is an XFS volume created with ftype=0, which lacks d_type; OverlayFS then either refuses to mount (invalid argument) or behaves incorrectly. The too many levels of symbolic links variant means the stacked lower-layer depth exceeded the kernel’s limit, and backing filesystem does not support overlay means the underlying filesystem or kernel cannot host OverlayFS at all.

Common Causes

• Backing filesystem lacks d_type — XFS formatted with ftype=0 is the most common; OverlayFS requires ftype=1.
• Unsupported or too-old kernel — OverlayFS multi-lower support and overlay-on-overlay behaviour depend on a recent kernel.
• Max lower-layer / symlink depth exceeded — an image with an extreme number of stacked layers hits the kernel’s lower-dir or symlink-depth limit (too many levels of symbolic links).
• Corrupted overlay2 metadata — an unclean shutdown or partial prune leaves dangling l/ symlinks or orphaned layer directories.
• Storage-driver mismatch — the daemon was switched to overlay2 on a filesystem (or nested overlay) that cannot support it.

How to Reproduce the Error

Create an XFS volume without ftype support, point Docker’s data root at it, and start the daemon:

sudo mkfs.xfs -n ftype=0 -f /dev/nvme1n1
sudo mount /dev/nvme1n1 /var/lib/docker
sudo systemctl restart docker
docker run --rm alpine true

error creating overlay mount to /var/lib/docker/overlay2/.../merged: failed to mount overlay: invalid argument

journalctl -u docker shows the d_type warning explaining why.

Diagnostic Commands

Confirm the active storage driver and backing filesystem:

docker info | grep -i 'Storage Driver\|Backing Filesystem\|Supports d_type'

Supports d_type: false is the smoking gun. Check the XFS format directly:

sudo xfs_info /var/lib/docker | grep -i ftype     # ftype=1 required
mount | grep '/var/lib/docker'

Inspect the kernel version and OverlayFS availability:

uname -r
grep overlay /proc/filesystems          # should list "nodev overlay"

Read the daemon’s own diagnosis:

journalctl -u docker --no-pager | grep -i 'overlay\|d_type\|ftype\|graphdriver'

Step-by-Step Resolution

1. Reformat XFS with ftype=1 (or use ext4). This is the definitive fix for the d_type case. Back up data, then recreate the filesystem:

sudo systemctl stop docker
sudo umount /var/lib/docker            # after backing up
sudo mkfs.xfs -n ftype=1 -f /dev/nvme1n1
# or: sudo mkfs.ext4 -F /dev/nvme1n1
sudo mount /dev/nvme1n1 /var/lib/docker
sudo systemctl start docker
docker info | grep 'Supports d_type'   # now true

ext4 always supports d_type, so switching to ext4 sidesteps the XFS ftype requirement entirely.

2. Move the data root to a supported filesystem. If you cannot reformat the volume, point data-root at a partition that already reports Supports d_type: true:

{ "data-root": "/mnt/docker-ext4" }

3. Upgrade the kernel. For backing filesystem does not support overlay or nested-overlay failures, boot a kernel new enough for OverlayFS (and avoid running overlay2 on top of another overlay, e.g. inside some container-in-container setups).

4. Flatten image layers for symlink-depth errors. For too many levels of symbolic links, rebuild the offending image with fewer layers — combine RUN steps and use multi-stage builds to collapse history:

RUN apt-get update \
 && apt-get install -y --no-install-recommends curl ca-certificates \
 && rm -rf /var/lib/apt/lists/*

5. Reset a corrupted overlay2 tree. When metadata is damaged and the data is disposable, stop Docker and recreate the directory (this deletes all local images/containers):

sudo systemctl stop docker
sudo rm -rf /var/lib/docker/overlay2
sudo systemctl start docker
docker pull alpine:3.20        # re-pull what you need

6. Verify the driver after the fix. Run a throwaway container to confirm overlay2 now mounts cleanly:

docker run --rm alpine echo overlay-ok

How to Prevent the Issue

• Format any volume that will host /var/lib/docker with XFS ftype=1 or ext4, and verify docker info shows Supports d_type: true during host provisioning.
• Bake the filesystem check into your image/AMI build so no node ships with an ftype=0 data root.
• Keep hosts on a supported, reasonably recent kernel and avoid stacking overlay2 on top of another OverlayFS mount.
• Keep image layer counts modest with multi-stage builds and consolidated RUN steps to stay well under symlink-depth limits.
• Shut Docker down cleanly and avoid manual edits under overlay2/ to prevent metadata corruption.

Related Docker Errors

• no space left on device — a different /var/lib/docker storage failure, often confused with overlay mount errors; see the no space left on device guide.
• failed to solve with frontend dockerfile.v0 — a build-time failure rather than a runtime mount issue; see the failed to solve guide.
• More storage and runtime fixes in the Docker guides.