🚨 Docker Error Guide: 'error pulling image configuration: download failed' — Fix Pulls

Overview

error pulling image configuration: download failed means Docker fetched the image manifest successfully but failed to download the image config blob — the small JSON object the manifest references that describes the image (entrypoint, env, layer digests). Because the manifest resolved, authentication and repository lookup worked; the failure is in retrieving a specific blob, which the registry often serves from a CDN or a different backend host than the manifest.

The literal error appears near the start of a pull, before large layers download:

docker pull ghcr.io/org/app:1.4.0
1.4.0: Pulling from org/app
error pulling image configuration: download failed after attempts=6: dial tcp: lookup pkg-containers.githubusercontent.com: no such host

A TLS-interception variant reads:

error pulling image configuration: download failed after attempts=6: x509: certificate signed by unknown authority

Symptoms

• The pull prints Pulling from <repo> (so the manifest resolved) then fails with error pulling image configuration: download failed.
• The trailing detail names a different host than the registry (a CDN or blob-storage domain).
• Some images pull fine while others fail — the failing ones use a blob backend that is blocked.
• Retries occasionally succeed (transient), or fail consistently (blocked host / bad CA).

Common Root Causes

• Blob CDN host blocked or unresolvable — the config blob lives on a separate domain (e.g. pkg-containers.githubusercontent.com, *.cloudfront.net, production.cloudflare.docker.com) that a firewall or DNS blocks while the main registry is allowed.
• TLS interception without the CA trusted — a corporate MITM proxy presents a certificate the daemon does not trust, so the blob download fails with x509.
• Proxy misconfiguration — the daemon’s HTTPS_PROXY/NO_PROXY covers the registry but not the blob CDN, or vice versa.
• DNS resolution failure for the blob host specifically.
• Registry rate limiting — the config fetch is throttled (Docker Hub anonymous limits) after the manifest is served.
• Transient CDN/network errors — intermittent 5xx or connection resets from the blob backend.

Diagnostic Workflow

Read the trailing cause after download failed after attempts= — it names the failing host and reason:

docker pull <image> 2>&1 | tail -3
journalctl -u docker --since '5 min ago' | grep -i 'download failed\|image configuration'

Test reachability and DNS to the blob host it named (not just the registry):

getent hosts pkg-containers.githubusercontent.com
curl -sS -o /dev/null -w '%{http_code}\n' https://pkg-containers.githubusercontent.com/

If the reason is x509, check whether a MITM proxy CA is trusted by the daemon:

openssl s_client -connect <blob-host>:443 -servername <blob-host> </dev/null 2>/dev/null | openssl x509 -noout -issuer
ls /etc/docker/certs.d/ 2>/dev/null

Verify the daemon’s proxy allowlist includes the blob CDN:

systemctl show --property=Environment docker | tr ' ' '\n' | grep -i 'proxy'

Check for Docker Hub rate limiting on the config fetch:

TOKEN=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:library/alpine:pull" | jq -r .token)
curl -sI -H "Authorization: Bearer $TOKEN" https://registry-1.docker.io/v2/library/alpine/manifests/latest | grep -i ratelimit

Example Root Cause Analysis

Builds behind a new corporate firewall failed pulling GHCR images with:

error pulling image configuration: download failed after attempts=6: dial tcp: lookup pkg-containers.githubusercontent.com: no such host

ghcr.io itself was allowlisted, so the manifest resolved — but GHCR serves config and layer blobs from pkg-containers.githubusercontent.com, which the firewall’s DNS policy did not resolve. The manifest succeeded and the config blob download failed, exactly matching the error’s trailing host.

The fix was to add the blob CDN domain (pkg-containers.githubusercontent.com) to the firewall/DNS allowlist alongside ghcr.io. For registries fronted by CDNs, the team documented the full set of domains each registry uses for blobs, so allowlists cover both the API host and the content backend. After the DNS allowlist update, pulls completed normally.

Prevention Best Practices

• Allowlist blob/CDN domains, not just the registry API host. Each major registry serves blobs from separate domains that must be reachable and resolvable.
• Trust the MITM CA in the daemon (via /etc/docker/certs.d/ or the system trust store) if a TLS-inspecting proxy is mandatory.
• Align proxy env across hosts and blob domains so HTTPS_PROXY/NO_PROXY covers the whole pull path.
• Authenticate to avoid rate limits on Docker Hub instead of pulling anonymously.
• Run a registry mirror / pull-through cache inside the network to collapse pulls to one trusted, reachable host.
• Retry with backoff in CI to ride out transient CDN blips.

Quick Command Reference

docker pull <image> 2>&1 | tail -3               # read the failing host + reason
getent hosts <blob-cdn-host>                     # DNS for the blob backend
curl -sS -o /dev/null -w '%{http_code}\n' https://<blob-cdn-host>/
openssl s_client -connect <blob-host>:443 </dev/null | openssl x509 -noout -issuer
systemctl show --property=Environment docker | tr ' ' '\n' | grep -i proxy

Conclusion

error pulling image configuration: download failed is a blob-download failure after a successful manifest fetch — the config JSON lives on a host the daemon could not reach or trust. Read the trailing host and reason: a blocked CDN domain, an untrusted MITM CA, a proxy gap, or a rate limit. Allowlist the registry’s blob domains, trust required CAs, and prefer a pull-through mirror. For TLS-specific failures, see the x509 certificate signed by unknown authority guide and the full Docker guides.