docker/cli · critical

image config verification failed for digest

Error message

image config verification failed for digest %s

What it means

After pulling the image config blob, a digest verifier recomputes the digest over the returned bytes and compares it to the digest the manifest referenced. A mismatch means the config bytes were corrupted in transit or in registry storage, or the manifest points at the wrong digest. The client deliberately refuses to trust unverifiable config.

Solutions

1. Re-pull from a known-good mirror or another tag of the same image.
2. Re-build and re-push the image so manifest and config digests are consistent.
3. Check registry storage integrity and the push pipeline for partial writes.
4. Verify no proxy/CDN is altering byte payloads (compression, transcoding).

Example fix

# suspect corruption -> repush the image
docker build -t myreg/img:fix . && docker push myreg/img:fix
# then pull the freshly-pushed tag

// On config verification failure, retry once from a mirror before failing hard.
if isConfigVerifyErr(err) {
    if m, e2 := mirrorClient.GetManifest(ctx, ref); e2 == nil {
        return m, nil
    }
}
return err

When it happens

Trigger: The config blob returned by the registry does not hash to the digest embedded in the manifest — registry storage bit-rot, a MITM altering bytes, a manifest republished with a stale config digest, or a partial/corrupted push.

Common situations: Corrupted registry backend; a transparent proxy re-encoding content; interrupted push leaving a manifest referencing a config that was never fully written; hardware/storage errors.

Related errors

• manifest verification failed for digest
• error: username is required
• error: password is required
• conflicting options: cannot specify both --password and…
• the --password-stdin option requires --username to be set

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/cbec1e92604be028. Report an issue: GitHub.

Appendix: source

Thrown at internal/registryclient/fetcher.go:127

		return types.ImageManifest{}, err
	}

	return types.NewOCIImageManifest(ref, manifestDesc, &mfst), nil
}

func pullManifestSchemaV2ImageConfig(ctx context.Context, dgst digest.Digest, repo distribution.Repository) ([]byte, error) {
	blobs := repo.Blobs(ctx)
	configJSON, err := blobs.Get(ctx, dgst)
	if err != nil {
		return nil, err
	}

	verifier := dgst.Verifier()
	if _, err := verifier.Write(configJSON); err != nil {
		return nil, err
	}
	if !verifier.Verified() {
		return nil, fmt.Errorf("image config verification failed for digest %s", dgst)
	}
	return configJSON, nil
}

// validateManifestDigest computes the manifest digest, and, if pulling by
// digest, ensures that it matches the requested digest.
func validateManifestDigest(ref reference.Named, mfst distribution.Manifest) (ocispec.Descriptor, error) {
	mediaType, canonical, err := mfst.Payload()
	if err != nil {
		return ocispec.Descriptor{}, err
	}
	desc := ocispec.Descriptor{
		Digest:    digest.FromBytes(canonical),
		Size:      int64(len(canonical)),
		MediaType: mediaType,
	}

	// If pull by digest, then verify the manifest digest.

View on GitHub (pinned to 4f84911bfe)