How to fix Error response from daemon: invalid layer digest in Docker

DockerINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 186 views

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.

Quick fix

Fixes Error response from daemon: invalid layer digest

# 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 > Restart
  1. Restart Docker and retry the operation
  2. Remove the corrupted image and re-pull
  3. Clear Docker's build cache and layer cache
  4. Check for network or proxy issues
docker — error
# 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 > Restart
Error response from daemon: invalid layer digest

What this error means

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.

Typical symptoms

  • docker pull fails with 'invalid layer digest' or 'invalid checksum digest format'
  • docker push fails with 'invalid layer digest' after 'Layer already exists'
  • Docker daemon fails to start with layer validation errors in logs
  • docker load fails when importing images from tar files
  • Intermittent pull failures where retrying sometimes succeeds
  • CI/CD pipelines fail randomly during image operations
  • docker build fails with digest verification errors
  • Filesystem layer verification failed for digest sha256:...

Common causes

  1. Network interruption or corruption during image layer download
  2. Corrupted layer data in Docker's local storage (/var/lib/docker)
  3. Empty or corrupted layer metadata files (diff files in layerdb)
  4. Registry returning inconsistent or corrupted layer data
  5. Proxy or firewall modifying layer content during transfer
  6. Incomplete image save/load operations
  7. Disk corruption or filesystem errors on Docker storage
  8. Version mismatch between Docker client and registry API

How to fix "Error response from daemon: invalid layer digest"

1Restart Docker and retry the operation

A simple restart can resolve transient issues by clearing in-memory state:

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

After restart, retry your original command:

bash
docker pull <image_name>:<tag>

If the error persists, proceed to the next steps.

2Remove the corrupted image and re-pull

Delete the problematic image from local storage and download it fresh:

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

bash
docker build --no-cache -t <image_name>:<tag> .
3Clear Docker's build cache and layer cache

Corrupted cache entries can cause digest validation failures:

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

Warning: The -a flag removes ALL unused images. Make sure you don't need any images that aren't currently in use by running containers.

4Check for network or proxy issues

Network problems can cause incomplete or corrupted downloads:

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

If you're behind a proxy, ensure it's configured correctly in Docker:

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

Add the following content:

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 and restart Docker:

bash
sudo systemctl daemon-reload
sudo systemctl restart docker
5Fix corrupted layer metadata files

The error can be caused by empty or corrupted metadata files in Docker's layer database:

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

If you find empty diff files, you have two options:

Option A: Remove the specific corrupted layer directory:

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

bash
sudo systemctl stop docker
sudo rm -rf /var/lib/docker/image
sudo systemctl start docker
# This will require re-pulling all images
6Verify registry-side integrity

Sometimes the issue originates from the registry itself:

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

bash
# Configure a registry mirror in /etc/docker/daemon.json
{
  "registry-mirrors": ["https://mirror.gcr.io"]
}
7Reset Docker storage completely (last resort)

If other fixes don't work, reset Docker's entire storage:

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

Linux - Complete reset:

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

Advanced notes

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:

bash
# 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/* | head

Registry API v2 validation: When pushing to a registry, Docker sends the digest with the layer. The registry validates that the received content matches:

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

bash
# Disable BuildKit
DOCKER_BUILDKIT=0 docker build .

# Or prune BuildKit cache specifically
docker builder prune

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

bash
# Specify platform explicitly
docker pull --platform linux/amd64 <image>

Frequently asked questions

What does "Error response from daemon: invalid layer digest" mean?
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.
How do I fix "Error response from daemon: invalid layer digest"?
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.
What causes "Error response from daemon: invalid layer digest"?
Network interruption or corruption during image layer download Corrupted layer data in Docker's local storage (/var/lib/docker) Empty or corrupted layer metadata files (diff files in layerdb)
Is the "Error response from daemon: invalid layer digest" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading