How to fix Error response from daemon: layer verification failed in Docker

What this error means

The "layer verification failed" error in Docker indicates that the SHA256 checksum of a downloaded image layer does not match its expected digest. Docker uses content-addressable storage where each layer is identified by its cryptographic hash. When you pull an image, Docker verifies that each downloaded layer matches its declared digest to ensure data integrity and security. This verification failure typically occurs during image pulls when the downloaded layer content is corrupted or incomplete. The most common cause is network instability during the download, causing partial or corrupted data to be written to disk. The error message usually includes the expected digest hash (sha256:...) that failed verification. The error can also indicate problems with the registry itself, where the stored layer data doesn't match its metadata. In virtualized environments (especially VirtualBox), known bugs with network interfaces can cause SSL/TLS issues that corrupt downloads.

Typical symptoms

• docker pull fails with 'filesystem layer verification failed for digest sha256:...'
• docker build fails during the FROM instruction when pulling the base image
• Image pulls fail intermittently - sometimes succeed, sometimes fail
• Error occurs on different layers each time, not consistently the same layer
• Larger layers (>100MB) fail more frequently than smaller ones
• docker-compose up fails when pulling images
• CI/CD pipelines fail randomly during image pull stages

Common causes

1. Network instability or packet loss during image layer download
2. VirtualBox network adapter bug when using bridged networking mode
3. Corrupted Docker local cache or storage
4. Private registry storage backend issues (especially S3-compatible storage like Minio)
5. Proxy or corporate firewall modifying download content
6. Insufficient disk space causing incomplete writes
7. TLS/SSL interception or certificate issues
8. Concurrent image operations causing race conditions

How to fix "Error response from daemon: layer verification failed"

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

# Then retry your image pull
docker pull <image_name>:<tag>

# Remove the problematic image (if partially downloaded)
docker rmi <image_name>:<tag> 2>/dev/null || true

# Prune unused data that might be corrupted
docker system prune -f

# Force a fresh pull
docker pull <image_name>:<tag>

# Stop all containers using the image
docker stop $(docker ps -q --filter ancestor=<image_name>)

# Remove the image
docker rmi -f <image_name>:<tag>

# Disable TCP checksumming offload (workaround)
sudo ethtool -K eth0 tx off rx off

# Check available disk space
df -h

# Check Docker's disk usage
docker system df

# Detailed breakdown
docker system df -v

# Remove all stopped containers, unused networks, and dangling images
docker system prune -a

# Also remove unused volumes (use with caution)
docker system prune -a --volumes

# Remove build cache
docker builder prune -a

# Stop Docker
sudo systemctl stop docker

# Remove all Docker data (backup important volumes first!)
sudo rm -rf /var/lib/docker

# Restart Docker (will recreate the directory structure)
sudo systemctl start docker

# Re-pull your images
docker pull <image_name>:<tag>

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

# Test direct connectivity to Docker Hub
curl -v https://registry-1.docker.io/v2/

# Create Docker daemon proxy config
sudo mkdir -p /etc/systemd/system/docker.service.d
sudo cat > /etc/systemd/system/docker.service.d/http-proxy.conf << EOF
[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"
EOF

# Reload and restart
sudo systemctl daemon-reload
sudo systemctl restart docker

# Check if the image exists and is accessible
docker manifest inspect <registry>/<image>:<tag>

# Try pulling with verbose output
docker pull <registry>/<image>:<tag> --debug

# On the registry server, delete the problematic layer
# Then rebuild and push the image
docker build --no-cache -t <registry>/<image>:<tag> .
docker push <registry>/<image>:<tag>

Advanced notes

# View the manifest of an image
docker manifest inspect <image>:<tag>

# Check local image layer digests
docker inspect <image> | jq '.[0].RootFS.Layers'

# Enable content trust
export DOCKER_CONTENT_TRUST=1

# Pull with signature verification
docker pull <image>:<tag>

# Check current MTU
ip link show

# Set a lower MTU if needed
sudo ip link set dev eth0 mtu 1400

# For Docker daemon, add to /etc/docker/daemon.json:
{
  "mtu": 1400
}

DOCKER_BUILDKIT=0 docker build .

# Enable debug logging
sudo dockerd --debug

# Or add to /etc/docker/daemon.json:
{
  "debug": true
}

Frequently asked questions

What does "Error response from daemon: layer verification failed" mean?

The "layer verification failed" error in Docker indicates that the SHA256 checksum of a downloaded image layer does not match its expected digest. Docker uses content-addressable storage where each layer is identified by its cryptographic hash. When you pull an image, Docker verifies that each downloaded layer matches its declared digest to ensure data integrity and security.

How do I fix "Error response from daemon: layer verification failed"?

This error occurs when Docker cannot verify the integrity of a downloaded image layer, typically due to network issues, corrupted downloads, or registry problems. Fixes include restarting Docker, clearing the cache, and re-pulling the image.

What causes "Error response from daemon: layer verification failed"?

Network instability or packet loss during image layer download VirtualBox network adapter bug when using bridged networking mode Corrupted Docker local cache or storage

Is the "Error response from daemon: layer verification failed" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• standard_init_linux.go: exec user process caused: no such file or directory

  How to fix 'exec user process caused: no such file or directory' in Docker

  MEDIUM

• Error response from daemon: image layer sha256 mismatch

  How to fix 'image layer sha256 mismatch' in Docker

  MEDIUM

• 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

  MEDIUM

• Error response from daemon: layer does not exist

  How to fix 'layer does not exist' in Docker

  MEDIUM

• WSL 2 requires an update to its kernel component

  How to fix 'WSL 2 requires an update to its kernel component' in Docker

  MEDIUM

• dial tcp: i/o timeout

  How to fix 'dial tcp: i/o timeout' in Docker

  MEDIUM

Official resources & further reading

• 📚Docker Official Documentation
• 📖
  Docker Docs: OverlayFS storage driver(Official Docs)
• 💬
  Stack Overflow: Filesystem layer verification failed for digest(Stack Overflow)
• 💬
  Stack Overflow: All public image pulls fail with verification error(Stack Overflow)
• 🐙
  GitHub moby/moby: Filesystem layer verification failed for digest(GitHub)
• 🐙
  GitHub moby/moby: Filesystem layer verification failure with recent docker server(GitHub)
• 🐙
  GitHub distribution: Registry corrupts uploaded layers with 3rd-party S3(GitHub)
• 📝
  Dev.to: 100 Common Docker Errors & Solutions