How to fix Error response from daemon: layer does not exist in Docker

DockerINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 253 views

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.

Quick fix

Fixes Error response from daemon: layer does not exist

# 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>
  1. Identify the affected image or container
  2. Restart the Docker daemon
  3. Remove and re-pull the affected image
  4. Prune unused Docker data
docker — error
# 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>
Error response from daemon: layer does not exist

What this error means

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.

Typical symptoms

  • docker run fails with 'Error response from daemon: layer does not exist'
  • docker build fails with 'failed to get layer sha256:...: layer does not exist'
  • docker push or docker save operations fail unexpectedly
  • Docker daemon fails to start with layer-related errors in logs
  • Intermittent failures where retrying the same command sometimes works
  • Multi-stage builds fail at random stages
  • docker-compose up fails for specific services

Common causes

  1. Corrupted Docker storage due to interrupted image pull or system crash
  2. Disk space exhaustion during image download or build
  3. Storage driver inconsistency between Docker metadata and actual layer files
  4. Race conditions in CI/CD pipelines with parallel image operations
  5. Incomplete or failed image layer download from registry
  6. Docker daemon not properly shut down, leaving inconsistent state
  7. Manual deletion of files in /var/lib/docker directory
  8. Switching between Linux and Windows containers (Docker Desktop)

How to fix "Error response from daemon: layer does not exist"

1Identify the affected image or container

First, determine which image is causing the problem. The error message usually contains a SHA256 hash of the missing layer.

bash
# 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.

2Restart the Docker daemon

A simple restart often resolves transient layer issues by reinitializing Docker's storage state:

bash
# 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 > Restart

After restart, retry your original command. If the error persists, proceed to the next steps.

3Remove and re-pull the affected image

Delete the corrupted image and download it fresh from the registry:

bash
# 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:

bash
# Force rebuild without cache
docker build --no-cache -t <image_name>:<tag> .
4Prune unused Docker data

Clean up dangling and unused Docker resources that may be causing conflicts:

bash
# 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 prune

Warning: 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.

5Check and free disk space

Insufficient disk space can cause layer corruption during downloads:

bash
# Check disk usage
df -h

# Check Docker's disk usage specifically
docker system df

# See detailed breakdown
docker system df -v

If disk space is low:

bash
# Remove stopped containers
docker container prune

# Remove unused volumes
docker volume prune

# Remove build cache
docker builder prune

Ensure at least 10-20% free space on the Docker storage partition (usually where /var/lib/docker resides).

6Reset Docker to factory defaults (last resort)

If other solutions fail, reset Docker's storage entirely:

Docker Desktop (Windows/Mac):
Settings > Reset > Reset to factory defaults

Linux - Remove all Docker data:

bash
# 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.

7Fix CI/CD pipeline race conditions

In CI/CD environments, parallel jobs can cause layer conflicts. Implement these safeguards:

yaml
# 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
          done

For multi-stage builds, consider building stages separately:

bash
# Build and tag intermediate stages explicitly
docker build --target builder -t myapp:builder .
docker build --target runtime -t myapp:latest .

Advanced notes

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:

bash
# 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:

bash
# 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:

bash
# Check manifest
docker manifest inspect <registry>/<image>:<tag>

# For private registries, check the registry's storage backend

Windows 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:

bash
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.

Frequently asked questions

What does "Error response from daemon: layer does not exist" mean?
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.
How do I fix "Error response from daemon: layer does not exist"?
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.
What causes "Error response from daemon: layer does not exist"?
Corrupted Docker storage due to interrupted image pull or system crash Disk space exhaustion during image download or build Storage driver inconsistency between Docker metadata and actual layer files
Is the "Error response from daemon: layer does not exist" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading