docker pull access denied: 5 Reasons Image Pulls Get Rejected (and the Fix)

Symptom: the pull gets rejected

pull access denied for myapp/api, repository does not exist or may
require 'docker login': denied: requested access to the resource is denied

One-line diagnosis: the registry (usually Docker Hub) refuses anonymous access to this image. Only two things cause that: "this repository doesn't exist", or "it exists but you lack permission". The error is deliberately vague (for security, it doesn't distinguish the two) — debugging means eliminating each cause.

Five causes, ranked by frequency

1. Misspelled image name (most common)

First, get the image-name parsing rules straight:

nginx                    → docker.io/library/nginx (official image)
bitnami/nginx            → docker.io/bitnami/nginx (user/org image)
registry.example.com/app → image on a private registry

Two frequent mistakes: pulling a personal image as if it were official (docker pull myapp resolves to library/myapp, which doesn't exist), or adding/dropping a path segment. Check the full path and spelling on the Docker Hub page first.

2. The tag doesn't exist

manifest for myapp/api:v1.2 not found is the sibling error — the repo exists but the tag is wrong. The assumption that every image has a latest tag is the classic trap: official images maintain latest, personal images often only ever pushed version tags. Check the Tags list on the Hub page; don't write tags from memory.

3. Not logged in to the private registry (or wrong account)

docker login                       # Docker Hub by default
docker login registry.example.com  # private / self-hosted registry
cat ~/.docker/config.json          # which registries, which accounts

Common traps: logged in with the company account while pulling a personal repo (or vice versa); expired CI credentials; logged in, then switched docker contexts. Re-login to the right registry.

4. Docker Hub rate limits (different error, same neighborhood)

Anonymous pulls are capped at 100 per 6 hours (per IP). The over-limit error is toomanyrequests: You have reached your pull rate limit — a different thing from access denied, but frequently confused with it. A logged-in free account gets 200, which is usually plenty.

5. Mainland China networks: configure a registry mirror

Direct connections to Docker Hub from mainland China often time out or get reset, producing a zoo of error shapes (timeout, EOF, unexpected status). The standard fix is a mirror in /etc/docker/daemon.json:

{
  "registry-mirrors": ["https://docker.m.daocloud.io"]
}

Then sudo systemctl restart docker. Watch out: daemon.json must not have trailing commas — break it and the daemon won't start; see Cannot connect to the Docker daemon for that diagnosis.

The triage flow (one minute)

# 1. What's the full error? (access denied / not found / rate limit point in different directions)
docker pull myapp/api:v1.2

# 2. Login state
docker login

# 3. Try an official image — if it pulls, the problem is name/permissions; if not, it's the network
docker pull hello-world

# 4. Network case: is the mirror active?
docker info | grep -A3 "Registry Mirrors"

Step 3 is the fork: hello-world fails too → network/rate limit (causes 4/5); only your image fails → name/permissions (causes 1/2/3).

Telling the neighboring errors apart

| Error | Meaning | Guide | |---|---|---| | pull access denied | repo missing or no permission | this post | | manifest ... not found | repo exists, tag is wrong | manifest unknown | | toomanyrequests | rate limited | log in or wait | | i/o timeout / EOF | network unreachable | mirror config (cause 5) |

Checklist

1. Full image path check: official = no prefix, personal = with username, private = with hostname
2. Does the tag exist? Verify on the Hub Tags page — never assume latest
3. docker login against the right registry? See ~/.docker/config.json
4. Is the error access denied or rate limit? The latter means login/wait
5. The docker pull hello-world fork test: network or permission?
6. Mainland networks: configure registry-mirrors

Provided by ToolVault. Related tools: Dockerfile Generator, Linux Cheatsheet. Related reading: manifest unknown, Docker daemon unreachable. See the homepage for more developer tools.