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.
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.
A simple restart often resolves transient network or cache issues:
# 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>The restart clears Docker's network connections and reinitializes its state. Try pulling the image 2-3 times as the error can be intermittent.
Clear any corrupted cached data before re-downloading:
# 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>If the image is used by running containers, stop them first:
# Stop all containers using the image
docker stop $(docker ps -q --filter ancestor=<image_name>)
# Remove the image
docker rmi -f <image_name>:<tag>If you're running Docker inside a VirtualBox VM, a known bug in bridged networking causes SSL/TLS errors that corrupt downloads:
Solution: Switch to NAT networking
1. Power off the VM
2. Open VirtualBox Manager
3. Select your VM > Settings > Network
4. Change "Attached to" from "Bridged Adapter" to "NAT"
5. Start the VM and retry
If you need bridged networking for other purposes, try:
# Disable TCP checksumming offload (workaround)
sudo ethtool -K eth0 tx off rx offThis VirtualBox bug affects downloads over a few seconds and has been documented since 2014.
Insufficient disk space can cause incomplete layer writes:
# Check available disk space
df -h
# Check Docker's disk usage
docker system df
# Detailed breakdown
docker system df -vIf space is low, clean up Docker resources:
# 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 -aEnsure at least 10-20% free space on the partition containing /var/lib/docker.
If other solutions fail, resetting Docker clears all potentially corrupted storage:
Docker Desktop (Windows/Mac):
Docker icon > Preferences/Settings > Reset > Reset to factory defaults
Linux:
# 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>Warning: This removes ALL Docker data including containers, images, and volumes. Export important data before proceeding.
Corporate proxies or firewalls can interfere with downloads:
# Check if a proxy is configured
env | grep -i proxy
# Test direct connectivity to Docker Hub
curl -v https://registry-1.docker.io/v2/If behind a proxy, configure Docker to use it:
# 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 dockerFor SSL inspection proxies, you may need to add the proxy's CA certificate to Docker's trusted certificates.
If using a private registry, the problem may be on the registry side:
# Check if the image exists and is accessible
docker manifest inspect <registry>/<image>:<tag>
# Try pulling with verbose output
docker pull <registry>/<image>:<tag> --debugFor registry administrators:
If using S3-compatible storage (like Minio) as a backend, there are known issues with multipart uploads that can corrupt layers. Solutions include:
1. Update to the latest registry version (fixes in distribution/distribution#2205)
2. Check S3 storage backend health
3. Re-push the affected images
4. Delete and rebuild the image in the registry
# 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>Understanding the verification process: When Docker pulls an image, it first fetches the manifest containing layer digests (SHA256 hashes). As each layer is downloaded, Docker computes its hash and compares it to the expected digest. A mismatch triggers the "verification failed" error.
Layer verification internals:
# View the manifest of an image
docker manifest inspect <image>:<tag>
# Check local image layer digests
docker inspect <image> | jq '.[0].RootFS.Layers'Registry content trust: Docker Content Trust (DCT) provides additional verification through digital signatures:
# Enable content trust
export DOCKER_CONTENT_TRUST=1
# Pull with signature verification
docker pull <image>:<tag>MTU issues: In some network configurations, especially with VPNs or overlay networks, MTU mismatches can cause packet fragmentation that corrupts downloads:
# 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
}BuildKit considerations: If using BuildKit (DOCKER_BUILDKIT=1), it has its own caching and download mechanisms. Try disabling it to isolate the issue:
DOCKER_BUILDKIT=0 docker build .Debugging download issues:
# Enable debug logging
sudo dockerd --debug
# Or add to /etc/docker/daemon.json:
{
"debug": true
}Then check journalctl -u docker for detailed layer download logs.
Content corruption by proxies: Some corporate proxies perform deep packet inspection and may corrupt binary data. Test by temporarily bypassing the proxy or using a different network.
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