Docker · Beginner · 15 min
Fix Docker 'pull access denied' and push errors
Fix Docker pull access denied and push insufficient_scope: wrong name, missing tag, login, token scope for Docker Hub, GHCR, ACR and ECR.
Every pull and push goes through a registry, and each refusal has its own message. This runbook maps the Docker 29 messages (and the older wording) to the cause, checks tags without pulling, fixes logins and push rights, and trusts a private CA without turning TLS off. Commands were run on Ubuntu 26.04 with Docker Engine 29.1.3.
On this page
See it run
A short replay of real output from commands in this guide, captured on a WSL2 Ubuntu test machine (Docker 29.1.3, Docker Hub and a throwaway local registry:2 with a fake password). The typing is replayed, and the host name, account and MAC addresses are redacted. Your output will differ, and a test machine is not a production server.
Text version of this demo
ops@web-01:~$ docker pull obf-no-such-org/no-such-app:1.0 Error response from daemon: pull access denied for obf-no-such-org/no-such-app, repository does not exist or may require 'docker login' ops@web-01:~$ docker manifest inspect alpine:3.99-no-such-tag no such manifest: docker.io/library/alpine:3.99-no-such-tag ops@web-01:~$ docker pull localhost:5002/team/app:1 Error response from daemon: failed to resolve reference "localhost:5002/team/app:1": pull access denied, repository does not exist or may require authorization: authorization failed: no basic auth credentials ops@web-01:~$ docker login localhost:5002 -u demo --password-stdin < ~/demo/password.txt 2>/dev/null Login Succeeded ops@web-01:~$ docker pull -q localhost:5002/team/app:1 localhost:5002/team/app:1
docker pull, docker push and docker run with an image that is not local all talk to a registry. When that fails, the message names one of a few causes: the repository name is wrong or private, the tag does not exist, you are not logged in or not allowed, the registry's TLS certificate is not trusted, or the registry is limiting you. This runbook reads the message, confirms the cause without pulling anything, and fixes it.
Commands and output were captured on an Ubuntu 26.04 test machine with Docker Engine 29.1.3, against Docker Hub and two throwaway local registries (registry:2, one with a password and one with a self-signed certificate). Docker 29 reports several of these errors with different wording than older versions; both are listed where they differ. The older wording is quoted for recognition and was not reproduced here.
0. Rules of engagement
- Never put a password on the command line. Use
--password-stdinor a credential helper; command lines end up in shell history and process lists. - Do not disable TLS checks to make an error go away. Adding a registry to
insecure-registriesturns off certificate verification for it; trust the right certificate instead (section 5). - Check the exact image reference first. Most of these errors come from a typo in the name, the tag or the registry host.
1. Read the message
| Message (Docker 29.1.3) | Older Docker versions | Cause | Go to |
|---|---|---|---|
pull access denied for NAME, repository does not exist or may require 'docker login' | same | Wrong name, a private repository, or not logged in (Docker Hub) | Section 2 |
failed to resolve reference "docker.io/library/alpine:3.99-no-such-tag": ... not found | manifest for ... not found: manifest unknown | The repository exists, the tag does not | Section 3 |
pull access denied, ... authorization failed: no basic auth credentials | no basic auth credentials | A private registry, and you have not logged in to it | Section 4 |
login attempt to http://HOST/v2/ failed with status: 401 Unauthorized | unauthorized: incorrect username or password | Wrong user name, password or token | Section 4 |
push access denied, ... insufficient_scope: authorization failed | denied: requested access to the resource is denied | You are logged in (or not), but may not push to that namespace | Section 4 |
tls: failed to verify certificate: x509: certificate signed by unknown authority | same | The registry uses a certificate your host does not trust | Section 5 |
toomanyrequests: ... | same | Registry rate limit (Docker Hub limits anonymous pulls) | Section 6 |
# Real output from the test machine: a repository that does not exist on Docker Hub
Error response from daemon: pull access denied for obf-no-such-org/no-such-app, repository does not exist or may require 'docker login'All of these exit with code 1.
2. Wrong name or private repository
Docker Hub answers the same way for a repository that does not exist and for a private one you may not read, so the message cannot tell you which. Check, in this order:
- The full reference.
nginxmeansdocker.io/library/nginx;myorg/appmeansdocker.io/myorg/app. An image from another registry needs its host in the name:ghcr.io/myorg/app,registry.example.com:5000/team/app. - Spelling and case. Repository names are lowercase.
- Whether it is private. If it is, log in (section 4) with an account that may read it.
3. The tag does not exist
# Real output from the test machine (Docker 29.1.3)
Error response from daemon: failed to resolve reference "docker.io/library/alpine:3.99-no-such-tag": docker.io/library/alpine:3.99-no-such-tag: not foundCheck a tag without pulling the image:
# Ask the registry for the manifest only; exit code 0 means the tag exists
docker manifest inspect alpine:3.99-no-such-tag# Real output from the test machine
no such manifest: docker.io/library/alpine:3.99-no-such-tagFind the tags the publisher actually provides on the registry's web page or in its documentation, and pin a version that exists. A tag that existed last month can be removed; pinning by digest (image@sha256:...) protects you from that and from a tag that moves.
4. Login and permissions
# Real output from the test machine: a private registry, no login yet
Error response from daemon: failed to resolve reference "localhost:5002/team/app:1": pull access denied, repository does not exist or may require authorization: authorization failed: no basic auth credentials# Log in to that registry; the password comes from stdin, not from the command line
docker login localhost:5002 -u demo --password-stdin < password.txt# Real output from the test machine with a wrong password
Error response from daemon: login attempt to http://localhost:5002/v2/ failed with status: 401 Unauthorized- The host in
docker loginmust match the host in the image name, including the port. Logging in to Docker Hub does nothing forghcr.io. - Many registries want a token, not your account password: GitHub Container Registry, GitLab, and Docker Hub accounts with two-factor authentication.
- Check what is stored:
cat ~/.docker/config.jsonlists the registries you are logged in to (the secrets themselves sit in a credential helper, or base64-encoded in that file if none is configured, which is why Docker warns about unencrypted credentials).
Pushing needs write access to the namespace in the image name:
# Real output from the test machine: pushing to a Docker Hub namespace we do not own
push access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failedTag the image into a namespace you own (docker tag app myuser/app:1), or ask the owner of the organization for push rights.
4.1 Push access denied: insufficient_scope: authorization failed
insufficient_scope means the registry accepted your identity but the token it issued does not allow writing to this repository. Pulling the same image may work. Check, in this order:
- The name. The first part after the registry host must be a namespace you may write to.
docker push nginxordocker push someoneelse/appfails even when you are logged in. Rundocker image lsand retag withdocker tag SOURCE REGISTRY/NAMESPACE/NAME:TAG. - The token's scope. A read-only token logs in successfully and fails only on push. Compare with the table below.
- The registry host.
docker loginstores credentials per host. Check~/.docker/config.jsonfor the exact host you push to.
| Registry | What push needs | Common cause of insufficient_scope |
|---|---|---|
| Docker Hub | A personal access token with Read & Write (or Read, Write, Delete) permission, or your password | A read-only access token, or pushing to another user's or organization's namespace |
GitHub Container Registry (ghcr.io) | A classic personal access token with write:packages, or GITHUB_TOKEN with packages: write | A token with only read:packages; a workflow without permissions: packages: write; a package that grants the workflow's repository no write access (package settings, Manage Actions access); an uppercase letter in the image name, which must be lowercase |
| Azure Container Registry | az acr login --name REGISTRY as an identity with the AcrPush role on the registry (registries with repository-scoped permissions use a repository writer role instead) | The identity has only AcrPull or Reader, or the role assignment has not propagated yet |
| Amazon ECR | aws ecr get-login-password piped to docker login --username AWS --password-stdin, and IAM permissions for ecr:PutImage and the upload actions | An expired login (tokens last 12 hours), a missing IAM permission, or a repository that does not exist: ECR does not create it on push |
A GitHub Actions job that pushes to GHCR needs the permission set explicitly, because the default token may be read-only:
# Minimal job permissions for pushing to ghcr.io with the built-in token
permissions:
contents: read
packages: write
steps:
- uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}Verify with a push of a throwaway tag, then check that the tag exists with docker manifest inspect REGISTRY/NAMESPACE/NAME:TAG. Only the Docker Hub case in the output above was reproduced on the test machine; the GHCR, ACR and ECR rows follow the registry documentation and were not run.
5. x509: certificate signed by unknown authority
# Real output from the test machine: a registry with a self-signed certificate
Error response from daemon: failed to resolve reference "10.0.2.15:5443/team/app:1": failed to do request: Head "https://10.0.2.15:5443/v2/team/app/manifests/1": tls: failed to verify certificate: x509: certificate signed by unknown authorityThe Docker daemon, not your shell, verifies the certificate. Give it the CA that signed the registry's certificate, in a folder named exactly after the registry host and port:
# Trust a private CA for one registry only (no daemon restart needed)
sudo mkdir -p /etc/docker/certs.d/registry.example.com:5443
sudo cp company-ca.crt /etc/docker/certs.d/registry.example.com:5443/ca.crtOn the test machine this made the same pull succeed straight away. Behind a company proxy that inspects TLS, the "unknown authority" is the proxy; add the company CA the same way, or to the system trust store and restart Docker. On Docker Desktop, add the CA to the operating system's trust store.
6. Rate limits and timeouts
toomanyrequestscomes from the registry. Docker Hub limits pulls, more strictly for anonymous users; the exact limits are on Docker's documentation page and have changed over time. Log in (even a free account gets a higher limit), use a pull-through cache or mirror for CI, and stop pulling the same image in every job.TLS handshake timeoutorClient.Timeout exceededpoint to the network or a proxy, not to the registry's permissions. Test withcurl -sS -o /dev/null -w '%{http_code}\n' https://registry-1.docker.io/v2/: any HTTP status (401 is normal here) proves the network path works.
These two cases were not reproduced on the test machine.
7. Verify
# The tag exists and you may read it; then pull by digest for a repeatable result
docker manifest inspect IMAGE:TAG >/dev/null && echo "tag exists"
docker pull IMAGE:TAG
docker image inspect --format '{{index .RepoDigests 0}}' IMAGE:TAG8. Rollback and prevention
- Rollback:
docker logout HOSTremoves a login you added; remove acerts.dfolder you created if the CA was wrong. - Use a credential helper instead of plain
config.jsonsecrets on shared machines and CI runners. - Pin images by digest in production manifests, and keep the tag next to it for humans.
- Mirror the base images you depend on into your own registry, so a deleted tag or a rate limit upstream does not stop your builds.
References
Official reference
Technical steps are original explanations; consult the upstream documentation for version-specific details.
Behavior differs by distribution and tool version. Commands are examples for authorized systems; review output for secrets before sharing.
Found this useful?
Follow us on YouTube for video explainers, and find us on Facebook to keep up with what is new.