This error occurs when Docker cannot find a required image layer during operations like run, build, push, or save. Common fixes include restarting the Docker daemon, pruning corrupted data, or re-pulling the affected images.
The "layer does not exist" error in Docker indicates that the Docker daemon cannot locate a required filesystem layer for an image. Docker images are composed of multiple read-only layers stacked on top of each other, and each layer contains filesystem changes from the previous one. When any layer in this chain is missing or corrupted, Docker cannot assemble the complete image. This error typically surfaces during operations that require accessing image layers: running a container, building an image, pushing to a registry, or saving an image to a tar file. The layer reference exists in Docker's metadata, but the actual layer data is missing from the storage backend. The root cause is usually corruption in Docker's local storage, often triggered by interrupted operations (like a system crash during an image pull), disk space issues, or problems with Docker's storage driver (overlay2, devicemapper, etc.). In CI/CD environments, aggressive caching or parallel builds can also cause layer conflicts.
First, determine which image is causing the problem. The error message usually contains a SHA256 hash of the missing layer.
# Check which images reference the problematic layer
docker images --digests
# Inspect a specific image's layers
docker inspect <image_name> | grep -A 50 "RootFS"
# List all image layers
docker history <image_name>Note the image name(s) associated with the missing layer for targeted cleanup.
A simple restart often resolves transient layer issues by reinitializing Docker's storage state:
# On Linux with systemd
sudo systemctl restart docker
# On older systems
sudo service docker restart
# On Docker Desktop (Windows/Mac)
# Right-click the Docker icon in system tray > RestartAfter restart, retry your original command. If the error persists, proceed to the next steps.
Delete the corrupted image and download it fresh from the registry:
# Remove the problematic image
docker rmi <image_name>:<tag>
# If the image is in use, force remove it
docker rmi -f <image_name>:<tag>
# Re-pull the image
docker pull <image_name>:<tag>If the image was built locally, rebuild it:
# Force rebuild without cache
docker build --no-cache -t <image_name>:<tag> .Clean up dangling and unused Docker resources that may be causing conflicts:
# Remove unused containers, networks, images, and build cache
docker system prune -a
# More aggressive cleanup including volumes (use with caution)
docker system prune -a --volumes
# Remove only dangling images (untagged)
docker image pruneWarning: The -a flag removes all unused images, not just dangling ones. Make sure you don't need any stopped containers or unused images before running this.
Insufficient disk space can cause layer corruption during downloads:
# Check disk usage
df -h
# Check Docker's disk usage specifically
docker system df
# See detailed breakdown
docker system df -vIf disk space is low:
# Remove stopped containers
docker container prune
# Remove unused volumes
docker volume prune
# Remove build cache
docker builder pruneEnsure at least 10-20% free space on the Docker storage partition (usually where /var/lib/docker resides).
If other solutions fail, reset Docker's storage entirely:
Docker Desktop (Windows/Mac):
Settings > Reset > Reset to factory defaults
Linux - Remove all Docker data:
# Stop Docker
sudo systemctl stop docker
# Backup any important volumes first!
# Then remove Docker's data directory
sudo rm -rf /var/lib/docker
# Restart Docker (will recreate the directory)
sudo systemctl start docker
# Re-pull your images
docker pull <image_name>:<tag>Warning: This removes ALL Docker data including containers, images, volumes, and networks. Export any important data first.
In CI/CD environments, parallel jobs can cause layer conflicts. Implement these safeguards:
# GitHub Actions example - serialize Docker operations
jobs:
build:
runs-on: ubuntu-latest
concurrency:
group: docker-build-${{ github.ref }}
cancel-in-progress: false
steps:
- name: Build with retry
run: |
for i in 1 2 3; do
docker build -t myimage . && break
echo "Attempt $i failed, retrying..."
docker system prune -f
sleep 5
doneFor multi-stage builds, consider building stages separately:
# Build and tag intermediate stages explicitly
docker build --target builder -t myapp:builder .
docker build --target runtime -t myapp:latest .Understanding Docker's layer storage: Docker stores layers in /var/lib/docker/<storage-driver>/. The overlay2 driver (default on modern Linux) stores layers in /var/lib/docker/overlay2/. Each layer directory contains a diff folder with the actual filesystem changes and metadata files.
Inspecting layer data directly:
# Find the layer directory
ls -la /var/lib/docker/overlay2/
# Check layer metadata
cat /var/lib/docker/image/overlay2/layerdb/sha256/<layer_id>/Storage driver issues: If you're using an older storage driver like devicemapper or aufs, consider migrating to overlay2:
# Check current storage driver
docker info | grep "Storage Driver"
# To change storage driver, edit /etc/docker/daemon.json:
{
"storage-driver": "overlay2"
}Note: Changing storage drivers requires removing all existing Docker data.
Registry-side issues: Sometimes the layer is missing from the source registry. Verify the image exists and is complete:
# Check manifest
docker manifest inspect <registry>/<image>:<tag>
# For private registries, check the registry's storage backendWindows containers: On Docker Desktop, switching between Linux and Windows containers can cause layer issues. Each mode has separate storage. If you switched modes, images from the other mode won't be accessible.
Buildkit considerations: If using BuildKit (DOCKER_BUILDKIT=1), layer caching works differently. Try disabling BuildKit to see if the issue is BuildKit-specific:
DOCKER_BUILDKIT=0 docker build .Content-addressable storage: Docker uses content-addressable storage where layers are identified by their SHA256 hash. If a layer's content changes but the hash doesn't match, Docker will report the layer as missing. This can happen with registry corruption or man-in-the-middle scenarios.
image operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker
cannot open '/etc/passwd': Permission denied
How to fix 'cannot open: Permission denied' in Docker
Error response from daemon: failed to create the ipvlan port
How to fix 'failed to create the ipvlan port' in Docker
toomanyrequests: Rate exceeded for anonymous users
How to fix 'Rate exceeded for anonymous users' in Docker Hub