Image pull failures — registry, auth, network · Docker & Containers

Pull failures happen at three layers: the registry, authentication, and network. Each has a distinct symptom.

Underneath every one of them is an HTTP exchange with a registry, and the status code of that exchange is the diagnosis. The CLI paraphrases it, often unhelpfully — pull access denied is printed for both “you are not logged in” and “this repository does not exist”, because a registry returns the same 401 for both by design so that private repository names cannot be enumerated.

The errors as the CLI prints them

docker pull myorg/myapp:1.0.0
# Error response from daemon: pull access denied for myorg/myapp
# (authentication required or insufficient_scope)
# → auth, repo permissions, or the repo does not exist

# Error response from daemon: Get "https://registry.example.com/v2/": dial tcp: lookup registry.example.com: no such host
# → DNS resolution failure, on the HOST, not in a container

# Error response from daemon: Get "https://registry.example.com/v2/": net/http: TLS handshake timeout
# → network path, MTU, or a middlebox

# Error response from daemon: Get "https://registry.example.com/v2/": x509: certificate signed by unknown authority
# → the daemon does not trust the registry's CA

# toomanyrequests: You have reached your pull rate limit.
# → HTTP 429; see the rate-limit section

# manifest for myorg/myapp:1.0.0 not found: manifest unknown
# → HTTP 404; the tag does not exist for this platform

The status code is the diagnosis

Status	Registry means	Fix
`401 Unauthorized`	No credentials, or the token expired	`docker login`; check the credential helper
`403 Forbidden`	Authenticated, but this identity lacks the scope	Repository permissions, not credentials
`404 Not Found`	Repository or tag does not exist for the requested platform	Check the tag, and check the platform
`429 Too Many Requests`	Rate limited	Authenticate, mirror, or wait out the window
`5xx`	Registry is unwell	Retry with backoff; check the registry’s status
TLS error, no status	The connection never became HTTP	CA trust, proxy interception, MTU

The 401 vs 403 distinction is the useful one and the CLI hides it. 401 means the registry did not accept who you are. 403 means it accepted who you are and refused what you asked for — so re-running docker login will not help and the fix is a permissions change on the repository.

Read-only / Safeget the real status code— Talk to the registry directly, the same way the daemon does.

REGISTRY=registry.example.com
REPO=myorg/myapp
TAG=1.0.0

# 1. Is the registry API reachable at all? An unauthenticated /v2/ probe
#    returns 200 or 401 on a healthy registry; anything else is the answer.
curl -sS -o /dev/null -w 'v2 probe: %{http_code}\n' "https://$REGISTRY/v2/"

# 2. The full response headers, including the auth challenge
curl -sSI "https://$REGISTRY/v2/$REPO/manifests/$TAG"

# 3. What authentication does it want?
curl -sSI "https://$REGISTRY/v2/" | grep -i 'www-authenticate'

# 4. Certificate chain, if TLS is the suspect
echo | openssl s_client -connect "$REGISTRY:443" -servername "$REGISTRY" 2>/dev/null \
| openssl x509 -noout -subject -issuer -dates

Step 3 returns the Www-Authenticate header, which names the token service the daemon will be redirected to. When a pull fails inside a corporate network and the registry itself is reachable, the token service frequently is not — it is often a different hostname on a different CDN, and a firewall rule that allowlists the registry alone will produce a failure that looks exactly like bad credentials.

Rate limits, precisely

Docker Hub’s published limits:

Account	Limit	Window
Unauthenticated	100 pulls “per IPv4 address or IPv6 /64 subnet”	6 hours
Personal (authenticated)	200	6 hours
Pro, Team, Business	Unlimited	—

Two details in that table do the diagnostic work.

The unauthenticated limit is per IP address or /64 subnet, not per host. An office or a CI cluster behind one NAT gateway shares a single allowance, so a single developer can exhaust it for everyone, and the machine that fails is not the machine that caused it. This is why “it works on my laptop” and “it fails in CI” coexist so often.

The window is 6 hours, which is a genuine reason “wait and retry” is not absurd — but it is a bad plan during a deploy, and it does nothing about the next occurrence.

Read-only / Safecheck your remaining allowance— Ask the token service and read the ratelimit headers.

# Anonymous token for a public repo
TOKEN=$(curl -sS \
'https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull' \
| sed -E 's/.*"token":"([^"]+)".*/\1/')

# HEAD the manifest and read the rate-limit headers
curl -sSI -H "Authorization: Bearer $TOKEN" \
https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest \
| grep -i ratelimit

Illustrative output:

ratelimit-limit: 100;w=21600
ratelimit-remaining: 20;w=21600
docker-ratelimit-source: 192.0.2.1

w=21600 is the 6-hour window in seconds. docker-ratelimit-source is the address the limit is being counted against — and when that address is your NAT gateway rather than your host, you have just proved the shared allowance theory without arguing about it.

The rate limit that only appears during an incident

The failure mode that costs a night: everything is fine for months because your images are cached locally. Then an incident happens, the response is to roll back, the rollback pulls an image that is not cached on this host, and Docker Hub returns 429 because the CI cluster on the same NAT gateway has been building all afternoon.

You cannot deploy the fix. The outage extends by however long it takes to either find credentials, find a mirror, or wait out a 6-hour window.

The preventive work is boring and takes an afternoon: authenticate every production host and every CI runner (authentication alone doubles the allowance and moves the count off the shared IP), and stand up a pull-through cache so the second pull of any image never leaves your network. Both are cheap. Neither can be done during the incident, which is precisely the point.

The 404 that is really a platform mismatch

docker pull myorg/myapp:1.0.0
# no matching manifest for linux/arm64/v8 in the manifest list entries

The tag exists. The registry has it. It simply has no image for your host’s platform, and a multi-platform manifest list that lacks your entry produces a 404-shaped failure.

Read-only / Safewhat platforms does this tag have— Inspect the manifest list without pulling anything.

REPO=myorg/myapp
TAG=1.0.0

# Every platform in the manifest list
docker manifest inspect "$REPO:$TAG" \
| python3 -c 'import json,sys; d=json.load(sys.stdin); [print(m["platform"]) for m in d.get("manifests",[{"platform":d.get("architecture")}])]'

# What platform is this host asking for?
docker info --format '{{.Architecture}} {{.OSType}}'

# Force a specific platform to confirm the theory
docker pull --platform linux/amd64 "$REPO:$TAG"

If --platform linux/amd64 succeeds on an arm64 host, the diagnosis is closed: the image is single-platform and your host is the wrong one. The pulled image will then fail to run with exec format error unless binfmt emulation is installed, which is a different lesson and a different problem — but at least it is now a known one.

What a pull actually does, and which step failed

docker pull is four HTTP exchanges, and knowing which one failed narrows the cause immediately:

GET /v2/ — a capability probe. A healthy registry answers 200 or 401 with a Www-Authenticate header. A TLS error or a timeout here means the failure is below HTTP: DNS, routing, certificate trust, or a proxy.
Token acquisition. The daemon follows the Www-Authenticate challenge to a token service — a different host for Docker Hub (auth.docker.io rather than registry-1.docker.io). Failures here look like authentication failures but are frequently connectivity to a host nobody allowlisted.
GET /v2/<name>/manifests/<ref> — fetch the manifest or manifest list. 404 here is a missing tag or a missing platform; 401/403 is permissions.
GET /v2/<name>/blobs/<digest> — fetch each layer, in parallel, usually redirected to object storage on a third hostname (S3, CloudFront, a CDN). A pull that authenticates fine, fetches the manifest fine, and then stalls at “Downloading” is almost always a firewall or proxy that permits the registry but not the blob store.

That last case is the one that defeats people, because every check they run against the registry hostname succeeds. docker pull output showing layer progress bars that reach a percentage and stop is the signature.

Steps 3 and 4 are also where max-concurrent-downloads matters: the daemon fetches several layers at once, so a link with limited concurrent connections through a proxy can fail some layers and not others, producing an intermittent pull that succeeds on retry.

Where the credentials actually live

Read-only / Safecredential audit— The daemon uses root's configuration, not yours, for some paths.

# Which registries does this user have entries for?
cat ~/.docker/config.json 2>/dev/null | python3 -m json.tool

# Is a credential helper in use? If so the file holds no secret and
# 'auths' will list the registry with no 'auth' key.
grep -o '"credsStore"[^,]*' ~/.docker/config.json 2>/dev/null

# Log in to a specific registry (prompts; do not pass a password on the
# command line, it lands in shell history and in ps output)
docker login registry.example.com

# Verify by asking the registry for something only an authenticated
# identity can see
docker manifest inspect registry.example.com/myorg/private-app:latest >/dev/null \
&& echo 'auth OK' || echo 'auth FAILED'

The user who ran docker login is not always the user who pulls

Three ways this bites:

sudo docker pull. Credentials in ~/.docker/config.json belong to your user. Under sudo the CLI reads /root/.docker/config.json, which is usually empty, and the pull fails as unauthenticated on a host where you demonstrably just logged in.
systemd units and CI runners. A unit running as a service account has its own home directory. Logging in interactively as a human does nothing for it.
Credential helpers with no session. credsStore delegates to a desktop keychain. On a headless host or in a CI job there is no keychain to unlock, so the helper returns nothing and the daemon proceeds anonymously.

The check that settles it is to run the failing pull as the identity that fails — sudo -u <service-user> docker pull ... — rather than as yourself.

For automation, prefer a registry access token with pull-only scope over an account password, and inject it with docker login --password-stdin reading from a file or a secret manager, never as an argument.

Registry mirrors

For rate-limited or bandwidth-constrained environments, configure a pull-through cache. The daemon tries the mirrors first and falls back to the original registry.

Configuration changepull-through mirror— Daemon-wide. registry-mirrors is reloadable with SIGHUP.

sudo tee /etc/docker/daemon.json >/dev/null <<'JSON'
{
"registry-mirrors": ["https://registry-mirror.example.com"]
}
JSON

sudo dockerd --validate --config-file=/etc/docker/daemon.json
sudo systemctl reload docker

# Verify the daemon accepted it
docker info --format '{{.RegistryConfig.Mirrors}}'

# Verify it is actually being used: pull something absent locally and
# watch the mirror's access log, or compare timings
docker image rm alpine:3.20 2>/dev/null || true
time docker pull alpine:3.20

registry-mirrors is one of the keys the daemon reloads on SIGHUP (which is what systemctl reload docker sends), so this does not require a restart and does not disturb running containers.

Two limits worth knowing before you rely on it: registry-mirrors applies to Docker Hub only — mirrors for other registries are configured per-registry in containerd’s host configuration, not with this key. And docker info confirming the mirror is configured does not confirm it is being used; only the mirror’s own access log or a timing difference does.

insecure-registries is not a fix for a certificate error

x509: certificate signed by unknown authority has a correct fix: install the registry’s CA certificate into the host trust store, at /usr/local/share/ca-certificates/ on Debian-family systems followed by update-ca-certificates, and restart the daemon so it re-reads the bundle.

Adding the registry to "insecure-registries" also makes the error go away, by turning off TLS verification for every pull from that host. On a registry that hosts your production images that means anything on the network path can substitute an image and the daemon will accept it. The error you were trying to silence was the system working.

The one legitimate use is a genuinely plaintext internal registry on an isolated network, deliberately, with that decision written down.

The diagnostic tree

flowchart TD
  S[Pull failed] --> Q0{"curl https://REGISTRY/v2/ succeeds?"}
  Q0 -- "TLS/DNS/timeout" --> C0["Below HTTP: DNS, routing,<br/>CA trust, proxy, MTU"]
  Q0 -- "gets a status" --> Q1{"Which status?"}
  Q1 -- 401 --> C1["Not authenticated:<br/>docker login, check WHICH user"]
  Q1 -- 403 --> C2["Authenticated, wrong scope:<br/>repository permissions"]
  Q1 -- 404 --> Q2{"Does the tag exist<br/>for your platform?"}
  Q2 -- no --> C3["Platform mismatch:<br/>docker manifest inspect"]
  Q2 -- yes --> C4["Wrong tag or repo name"]
  Q1 -- 429 --> C5["Rate limited: authenticate,<br/>mirror, or wait the 6h window"]
  Q1 -- 5xx --> C6["Registry unwell: retry,<br/>check its status page"]
  Q1 -- "200, but layers stall" --> C7["Blob store on a different host<br/>is blocked by proxy/firewall"]

What if the pull fails only on production hosts?

The registry works, your laptop pulls the image, and three production hosts cannot. That pattern eliminates the registry and the image, which is most of the search space, and leaves four candidates:

Different identity. Production pulls as a service account or as root; you pull as yourself. Reproduce with sudo -u as that account.
Different network path. Production sits behind an egress proxy your laptop does not use. Check systemctl show docker --property=Environment for HTTP_PROXY/HTTPS_PROXY/NO_PROXY — the daemon reads its proxy configuration from its own environment, not from your shell, and this is invisible from a terminal.
Different rate-limit bucket. Production shares a NAT address with something noisy. docker-ratelimit-source names it.
Different trust store. The production image of the host was built before the internal CA was rotated.

The check that separates them fastest is to run the raw curl probe from the production host. If curl succeeds where docker pull fails, the daemon’s environment differs from your shell’s, and the proxy variables are where to look.

Verification

Read-only / Safeverify the pull path— Proves a cold pull works, not merely that a cached image exists.

#!/usr/bin/env bash
set -euo pipefail
REF=registry.example.com/myorg/myapp:1.0.0

# Remove the local copy so the pull is real, not a cache hit
docker image rm "$REF" >/dev/null 2>&1 || true

# Pull, and fail the script if it fails
docker pull "$REF" || { echo 'FAIL: pull failed' >&2; exit 1; }

# Confirm what we actually got: digest and platform
docker image inspect "$REF" \
--format 'digest={{index .RepoDigests 0}} platform={{.Os}}/{{.Architecture}}'

# And that it matches the host we are on
host_arch=$(docker info --format '{{.Architecture}}')
img_arch=$(docker image inspect "$REF" --format '{{.Architecture}}')
[ "$host_arch" = "$img_arch" ] || echo "WARN: host $host_arch, image $img_arch"

echo OK

The docker image rm first is the part that makes this a verification rather than a formality. A docker pull that returns instantly because the image is already local proves nothing about the registry, the credentials or the network.