🚨 Docker Error Guide: 'overlay2/<hash>-init: no such file or directory' — Repair Corrupted Layer State

Overview

Docker fails to start a container or complete a pull because an overlay2 layer directory it expects — specifically an -init layer — is missing from the data root:

Error response from daemon: open /var/lib/docker/overlay2/2b7e4f9c1a3d5e8f-init/committed: no such file or directory

The overlay2 storage driver builds each container’s filesystem from a stack of layer directories under /var/lib/docker/overlay2/. An -init layer is a thin intermediate the daemon creates between the image and the writable container layer. When the daemon’s metadata references a layer directory that no longer exists on disk, the graphdriver state is corrupt and the operation aborts.

Symptoms

• docker run/docker start fails with overlay2/<hash>-init/...: no such file or directory.
• docker pull fails partway through, or a previously interrupted pull left the image in a broken state.
• docker images lists the image, but it cannot be run or removed cleanly.
• The error appears after an ungraceful shutdown, a disk-full event during a pull, or two concurrent pulls of the same image.
• Other images run fine; only specific ones with damaged layer state fail.

Common Root Causes

• Interrupted pull — a docker pull killed midway (Ctrl-C, network drop, OOM) leaves layer directories partially written and metadata out of sync.
• Concurrent pulls of the same image — two processes racing to materialize the same layers corrupt the graphdriver state.
• Disk-full during layer extraction — an ENOSPC mid-pull writes an incomplete -init layer, then space is freed, leaving a dangling reference.
• Ungraceful daemon/host shutdown — a crash or power loss between writing a layer and committing its metadata desyncs the two.
• Manual tampering — someone deleted directories under /var/lib/docker/overlay2/ by hand while the daemon still references them.
• Underlying filesystem errors — bad blocks or corruption on the volume backing the data root.

Diagnostic Workflow

First, confirm the storage driver is overlay2 and locate the data root:

docker info | grep -i 'Storage Driver\|Docker Root Dir'

Read the daemon log to capture the exact missing hash:

journalctl -u docker --since '15 min ago' | grep -i 'overlay2\|no such file'

Check whether the referenced layer directory actually exists on disk:

ls -ld /var/lib/docker/overlay2/2b7e4f9c1a3d5e8f-init 2>&1
ls /var/lib/docker/overlay2/ | grep 2b7e4f9c1a3d5e8f

Identify which image/container references the broken layer:

docker ps -a --filter status=created
docker image inspect <image> --format '{{json .GraphDriver.Data}}' 2>/dev/null

Rule out a full or inode-exhausted disk as the underlying trigger:

df -h /var/lib/docker
df -i /var/lib/docker

Check the filesystem health of the data-root volume if corruption is suspected:

dmesg | grep -i 'error\|ext4\|xfs\|i/o' | tail

Example Root Cause Analysis

A CI runner’s image pull was killed when the job timed out, and every subsequent build using that image failed:

docker run --rm registry.internal/builder:latest make
# Error response from daemon: open
#   /var/lib/docker/overlay2/2b7e4f9c1a3d5e8f-init/committed: no such file or directory

ls /var/lib/docker/overlay2/2b7e4f9c1a3d5e8f-init confirmed the directory did not exist, yet docker images still listed registry.internal/builder:latest. The interrupted pull had recorded layer metadata pointing at an -init directory that was never fully written. The graphdriver state for that image was corrupt.

The fix was to delete the broken image so its dangling layer references were removed, then re-pull cleanly:

# Remove the corrupted image (force, since it will not remove cleanly)
docker rmi -f registry.internal/builder:latest

# Clear any orphaned layers left behind
docker image prune -af

# Re-pull the image from scratch
docker pull registry.internal/builder:latest
docker run --rm registry.internal/builder:latest make   # succeeds

Where docker rmi itself failed because the daemon could not read the broken metadata, restarting the daemon first let it reconcile state, after which the removal and re-pull succeeded:

sudo systemctl restart docker
docker rmi -f registry.internal/builder:latest
docker pull registry.internal/builder:latest

Prevention Best Practices

• Let pulls finish — avoid killing docker pull; in CI, give image pulls a generous timeout separate from the build step.
• Serialize image pulls on shared builders so two jobs never materialize the same layers concurrently.
• Keep /var/lib/docker from filling up (monitor both df -h and df -i); a disk-full mid-pull is a leading cause of corrupt -init layers.
• Shut the daemon down gracefully (systemctl stop docker) before host maintenance rather than yanking power.
• Never delete files under /var/lib/docker/overlay2/ by hand; use docker rmi/docker system prune so metadata stays consistent.
• Watch dmesg for filesystem I/O errors on the data-root volume and replace failing storage promptly.

Quick Command Reference

# Confirm driver + capture the missing hash
docker info | grep -i 'Storage Driver'
journalctl -u docker --since '15 min ago' | grep -i 'overlay2\|no such file'

# Does the referenced layer exist?
ls -ld /var/lib/docker/overlay2/<hash>-init

# Remove the corrupted image and re-pull (primary fix)
docker rmi -f <image>
docker image prune -af
docker pull <image>

# If rmi fails, restart the daemon first to reconcile state
sudo systemctl restart docker

# Rule out disk / inode exhaustion as the trigger
df -h /var/lib/docker && df -i /var/lib/docker

Conclusion

overlay2/<hash>-init: no such file or directory means Docker’s graphdriver metadata references a layer directory that is not on disk — corrupted overlay2 state, almost always from an interrupted or concurrent pull, or a disk-full event mid-extraction. The reliable fix is to force-remove the affected image, prune orphaned layers, and re-pull it cleanly; if the daemon cannot even read the broken metadata, restart it first. Prevent recurrence by letting pulls finish, serializing them on shared builders, and keeping the data root from filling up.

For related storage-layer failures, see the error creating overlay mount guide, the input/output error overlay2 guide, the initializing graphdriver guide, and more fixes in the Docker guides.