This error occurs when Docker detects a mismatch between the expected and actual content of an image layer. Common fixes include removing corrupted images, clearing the Docker cache, and verifying network connectivity to the registry.
The "invalid layer digest" error in Docker indicates that the content of an image layer does not match its expected SHA256 hash (digest). Docker uses content-addressable storage where each layer is identified by a cryptographic hash of its contents. When Docker downloads or loads a layer and computes its hash, but the result doesn't match the expected digest, this error is raised. This error is a data integrity protection mechanism. Docker images are composed of multiple layers, and each layer's digest serves as both an identifier and a checksum. When a layer's actual content differs from what the digest promises, it could indicate corruption, tampering, or incomplete downloads. The error can occur during several operations: pulling images from a registry, pushing images to a registry, loading images from tar files, or when the Docker daemon starts and validates its local image cache. The underlying cause is typically network issues during transfers, corrupted local storage, or problems with the registry itself.
A simple restart can resolve transient issues by clearing in-memory state:
# On Linux with systemd
sudo systemctl restart docker
# On older Linux systems
sudo service docker restart
# On Docker Desktop (Windows/Mac)
# Right-click Docker icon in system tray > RestartAfter restart, retry your original command:
docker pull <image_name>:<tag>If the error persists, proceed to the next steps.
Delete the problematic image from local storage and download it fresh:
# Remove the image (get the exact name from the error)
docker rmi <image_name>:<tag>
# If the image is in use by containers, force remove
docker rmi -f <image_name>:<tag>
# Remove any dangling images that might be corrupted
docker image prune -f
# Re-pull the image
docker pull <image_name>:<tag>For locally built images, rebuild without cache:
docker build --no-cache -t <image_name>:<tag> .Corrupted cache entries can cause digest validation failures:
# Remove build cache
docker builder prune -a -f
# Remove all unused images (not just dangling)
docker image prune -a -f
# Full system cleanup (use with caution)
docker system prune -a -fWarning: The -a flag removes ALL unused images. Make sure you don't need any images that aren't currently in use by running containers.
Network problems can cause incomplete or corrupted downloads:
# Test connectivity to Docker Hub
curl -I https://registry-1.docker.io/v2/
# For private registries
curl -I https://<your-registry>/v2/
# Check if a proxy is interfering
echo $HTTP_PROXY $HTTPS_PROXYIf you're behind a proxy, ensure it's configured correctly in Docker:
# Create or edit proxy configuration
sudo mkdir -p /etc/systemd/system/docker.service.d
sudo nano /etc/systemd/system/docker.service.d/http-proxy.confAdd the following content:
[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 and restart Docker:
sudo systemctl daemon-reload
sudo systemctl restart dockerThe error can be caused by empty or corrupted metadata files in Docker's layer database:
# Find the layerdb directory
ls -la /var/lib/docker/image/overlay2/layerdb/sha256/
# Check for empty diff files (should be 71 bytes, not 0)
find /var/lib/docker/image/overlay2/layerdb -name "diff" -size 0If you find empty diff files, you have two options:
Option A: Remove the specific corrupted layer directory:
# Identify the layer from the error message
sudo rm -rf /var/lib/docker/image/overlay2/layerdb/sha256/<corrupted_layer_id>Option B: If many layers are corrupted, do a full cleanup:
sudo systemctl stop docker
sudo rm -rf /var/lib/docker/image
sudo systemctl start docker
# This will require re-pulling all imagesSometimes the issue originates from the registry itself:
# Inspect the image manifest
docker manifest inspect <image_name>:<tag>
# For private registries, check directly via API
curl -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
https://<registry>/v2/<repository>/manifests/<tag>If using a private registry:
1. Delete and re-push the image to the registry
2. Restart the registry container/service
3. Check the registry's storage backend for corruption
4. Verify disk space on the registry server
For Docker Hub or other public registries, try pulling from a mirror:
# Configure a registry mirror in /etc/docker/daemon.json
{
"registry-mirrors": ["https://mirror.gcr.io"]
}If other fixes don't work, reset Docker's entire storage:
Docker Desktop (Windows/Mac):
Settings > Troubleshoot > Reset to factory defaults
Linux - Complete reset:
# Stop Docker
sudo systemctl stop docker
# IMPORTANT: Backup any data you need first!
# Export important containers
docker export <container_id> > backup.tar
# Remove Docker's data directory
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 - containers, images, volumes, and networks. Only use this as a last resort after backing up important data.
Understanding Docker layer digests: Docker uses content-addressable storage (CAS) where each layer is identified by its SHA256 hash. The format is sha256:64-character-hex-string. This digest is computed from the layer's contents and serves as both an identifier and an integrity check.
Digest vs DiffID: Docker uses two types of identifiers:
- Digest: Hash of the compressed layer (used in registries)
- DiffID: Hash of the uncompressed layer (used locally in /var/lib/docker)
The error can occur when either doesn't match expected values.
Investigating layer files directly:
# Find layer storage location
docker info | grep "Docker Root Dir"
# Check layer metadata
cat /var/lib/docker/image/overlay2/layerdb/sha256/<layer_id>/diff
# Verify layer content integrity
sha256sum /var/lib/docker/overlay2/<layer_id>/diff/* | headRegistry API v2 validation: When pushing to a registry, Docker sends the digest with the layer. The registry validates that the received content matches:
PUT /v2/<repository>/blobs/uploads/<uuid>?digest=sha256:...If there's a mismatch, the registry returns an error with the invalid digest.
Docker 1.10 migration issues: The migration from Docker 1.9 to 1.10 changed layer addressing. Legacy images may have "invalid checksum digest format" errors. Solution: remove and re-pull affected images.
BuildKit considerations: BuildKit (DOCKER_BUILDKIT=1) has its own cache and layer handling. To isolate issues:
# Disable BuildKit
DOCKER_BUILDKIT=0 docker build .
# Or prune BuildKit cache specifically
docker builder pruneAir-gapped environments: When moving images via docker save/docker load, ensure:
- Files aren't modified during transfer
- Use checksums to verify tar files
- Transfer as binary, not text (avoid FTP ASCII mode)
Multi-platform images: Digest mismatches can occur when pulling for wrong architecture:
# Specify platform explicitly
docker pull --platform linux/amd64 <image>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