Docker "digest mismatch on pull" in CI

By Daniel Zoghalchali·Latchkey

Docker verifies each pulled layer against the digest in the manifest. A mismatch means the bytes received differ from what was expected - usually a corrupted download, a misbehaving registry mirror or proxy, or a damaged cache. The pull is rejected to avoid running a tampered or corrupt layer. A clean re-pull usually clears a one-off corruption.

What this error means

A docker pull fails with filesystem layer verification failed for digest sha256:... or unexpected commit digest ... expected .... A retry often succeeds.

Error: filesystem layer verification failed for digest sha256:9f3b... unexpected EOF

Common causes

A corrupted layer download

An interrupted or partially transferred layer fails verification against its digest.

A misbehaving mirror or proxy

A caching proxy serving stale or altered bytes produces a digest mismatch.

A damaged local cache

A corrupt local store can present a layer whose bytes no longer match the digest.

How to fix it

Re-pull on a clean store

1. Remove any partial image and pull again.
2. A fresh pull on a healthy runner usually verifies cleanly.

docker rmi -f myorg/app:ci || true
docker pull myorg/app:ci

Bypass a faulty mirror

1. If a registry mirror serves bad bytes, pull directly from the upstream registry.

docker pull registry-1.docker.io/myorg/app:ci

How to prevent it

• Prefer ephemeral runners with clean image stores per job.
• Validate registry mirrors; remove ones that serve corrupt layers.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation