How to fix Error response from daemon: image layer sha256 mismatch in Docker

DockerINTERMEDIATEMEDIUM

This error occurs when a Docker image layer's content doesn't match its expected SHA256 digest during pull, build, or push operations. The fix typically involves clearing Docker's cache, restarting the daemon, or re-pulling affected images.

What this error means

The "image layer sha256 mismatch" error indicates that Docker detected a discrepancy between the expected cryptographic hash (SHA256 digest) of an image layer and the actual content received. Docker uses content-addressable storage where every layer is identified by the SHA256 hash of its contents. When you pull or push an image, Docker verifies that each layer's content matches its advertised digest. This verification is a critical security feature that ensures image integrity and prevents tampering. When a mismatch occurs, it means the layer data was corrupted during transfer, the registry returned incorrect data, or local cache corruption has occurred. Docker refuses to proceed to protect against using potentially compromised or incomplete image data. The error commonly appears during image pulls (especially over unstable networks), when pushing to registries, or during builds that reference cached layers. It can also occur in CI/CD pipelines where parallel operations create race conditions in the layer cache.

How to fix "Error response from daemon: image layer sha256 mismatch"

1Retry the operation

Network glitches are the most common cause. A simple retry often succeeds:

bash

# Retry pulling the image
docker pull <image_name>:<tag>

# For builds, retry with fresh network connections
docker build -t <image_name> .

If the error occurs intermittently, network instability is likely the cause. Try switching to a wired connection or a different network.

2Clear Docker's build cache

Corrupted cache entries can cause persistent mismatch errors:

bash

# Remove build cache
docker builder prune -a

# For BuildKit specifically
docker buildx prune -a

# Remove dangling images that might have corrupted layers
docker image prune -f

After clearing the cache, retry your original operation.

3Restart the Docker daemon

Restarting Docker reinitializes its storage state and can resolve transient issues:

bash

# On Linux with systemd
sudo systemctl restart docker

# On older Linux systems
sudo service docker restart

# On Docker Desktop (Windows/Mac)
# Right-click the Docker icon in system tray > Restart

Wait a few seconds after restart before retrying the operation.

4Remove and re-pull the affected image

If a specific image consistently fails, remove it completely and pull fresh:

bash

# Remove all versions of the problematic image
docker rmi $(docker images <image_name> -q) 2>/dev/null || true

# Force remove if containers are using it
docker rmi -f <image_name>:<tag>

# Pull the image fresh
docker pull <image_name>:<tag>

For private registries, you may also need to clear cached credentials:

bash

docker logout <registry_url>
docker login <registry_url>

5Check for proxy or network interference

Corporate proxies and security appliances can corrupt Docker traffic:

bash

# Check if proxy is configured
env | grep -i proxy

# Test direct connection without proxy (if possible)
unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy
docker pull <image_name>:<tag>

If you must use a proxy, ensure it's configured correctly in Docker:

bash

# Create or edit Docker proxy config
sudo mkdir -p /etc/systemd/system/docker.service.d
sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf

Add:

ini

[Service]
Environment="HTTP_PROXY=http://proxy.example.com:8080"
Environment="HTTPS_PROXY=http://proxy.example.com:8080"
Environment="NO_PROXY=localhost,127.0.0.1"

Then reload:

bash

sudo systemctl daemon-reload
sudo systemctl restart docker

6Verify registry connectivity and image availability

Ensure the registry is accessible and the image exists:

bash

# Check if you can reach the registry
curl -I https://registry-1.docker.io/v2/

# For private registries
curl -I https://<your-registry>/v2/

# Verify the image manifest
docker manifest inspect <image_name>:<tag>

If using a private registry, check its health:

bash

# Check registry logs for errors
docker logs <registry_container_name>

# Verify the layer exists in registry storage
# (location depends on registry configuration)

7Prune all Docker data and start fresh

If the issue persists, perform a complete cleanup:

bash

# Stop all running containers
docker stop $(docker ps -q) 2>/dev/null || true

# Remove all Docker resources
docker system prune -a --volumes

# This removes:
# - All stopped containers
# - All networks not used by containers
# - All images without containers
# - All build cache
# - All volumes (use with caution!)

Warning: This deletes all local Docker data. Ensure you've backed up any important volumes before proceeding.

8Fix CI/CD race conditions

In CI/CD environments, parallel jobs can cause layer cache conflicts:

yaml

# GitHub Actions - add concurrency control
jobs:
  build:
    runs-on: ubuntu-latest
    concurrency:
      group: docker-${{ github.ref }}
      cancel-in-progress: false
    steps:
      - name: Build with retry logic
        run: |
          for i in 1 2 3; do
            docker build -t myimage . && exit 0
            echo "Attempt $i failed, cleaning up..."
            docker builder prune -f
            sleep 10
          done
          exit 1

For BuildKit, consider disabling shared cache in problematic scenarios:

bash

# Disable BuildKit if it's causing issues
DOCKER_BUILDKIT=0 docker build .

Advanced notes

Understanding content-addressable storage: Docker uses SHA256 hashes to identify layers. Each layer's digest is computed from its contents, ensuring that identical content always produces the same digest. This is why a mismatch indicates either corruption or tampering.

Verifying layer digests manually:

bash

# View image digests
docker images --digests

# Inspect layer chain
docker inspect <image> | jq '.[0].RootFS.Layers'

# Check manifest list (for multi-arch images)
docker manifest inspect --verbose <image>:<tag>

BuildKit-specific issues: BuildKit's garbage collection can race with multi-stage builds. If you see "content digest sha256:...: not found", try:

bash

# Increase BuildKit's GC keep duration
# In /etc/docker/daemon.json:
{
  "builder": {
    "gc": {
      "defaultKeepStorage": "20GB",
      "enabled": true
    }
  }
}

Storage driver considerations: The overlay2 storage driver is most reliable. Check your driver:

bash

docker info | grep "Storage Driver"

If using an older driver (aufs, devicemapper), consider migrating:

bash

# In /etc/docker/daemon.json:
{
  "storage-driver": "overlay2"
}

Registry corruption: For private registries, layer corruption can occur in the registry itself:

bash

# For Docker Registry v2, run garbage collection
docker exec -it registry bin/registry garbage-collect /etc/docker/registry/config.yml

# Then restart the registry
docker restart registry

Debugging with verbose output:

bash

# Enable debug mode for more details
DOCKER_DEBUG=1 docker pull <image>

# Check Docker daemon logs
journalctl -u docker.service -f

Network debugging: If you suspect network issues:

bash

# Test download speed and integrity
curl -o /dev/null -w "%{speed_download}" https://registry-1.docker.io/v2/

# Check for packet loss
ping -c 100 registry-1.docker.io | grep loss

Security implications: A consistent SHA256 mismatch from a trusted registry could indicate a man-in-the-middle attack. If this happens repeatedly on secure networks, investigate your network infrastructure for potential compromise.

How to fix Error response from daemon: image layer sha256 mismatch in Docker

What this error means

Typical symptoms

Common causes

How to fix "Error response from daemon: image layer sha256 mismatch"

Advanced notes

Related errors

Official resources & further reading