We earn commissions when you shop through the links below, at no extra cost to you. Our guides and technical recommendations are written independently of these relationships: a commission never decides what we recommend, how we diagnose a problem or what we publish, and the content does not depend on it. Affiliate disclosure

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.

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

  1. Never put a password on the command line. Use --password-stdin or a credential helper; command lines end up in shell history and process lists.
  2. Do not disable TLS checks to make an error go away. Adding a registry to insecure-registries turns off certificate verification for it; trust the right certificate instead (section 5).
  3. 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 versionsCauseGo to
pull access denied for NAME, repository does not exist or may require 'docker login'sameWrong 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 foundmanifest for ... not found: manifest unknownThe repository exists, the tag does notSection 3
pull access denied, ... authorization failed: no basic auth credentialsno basic auth credentialsA private registry, and you have not logged in to itSection 4
login attempt to http://HOST/v2/ failed with status: 401 Unauthorizedunauthorized: incorrect username or passwordWrong user name, password or tokenSection 4
push access denied, ... insufficient_scope: authorization faileddenied: requested access to the resource is deniedYou are logged in (or not), but may not push to that namespaceSection 4
tls: failed to verify certificate: x509: certificate signed by unknown authoritysameThe registry uses a certificate your host does not trustSection 5
toomanyrequests: ...sameRegistry 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:

  1. The full reference. nginx means docker.io/library/nginx; myorg/app means docker.io/myorg/app. An image from another registry needs its host in the name: ghcr.io/myorg/app, registry.example.com:5000/team/app.
  2. Spelling and case. Repository names are lowercase.
  3. 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 found

Check 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-tag

Find 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 login must match the host in the image name, including the port. Logging in to Docker Hub does nothing for ghcr.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.json lists 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 failed

Tag 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:

  1. The name. The first part after the registry host must be a namespace you may write to. docker push nginx or docker push someoneelse/app fails even when you are logged in. Run docker image ls and retag with docker tag SOURCE REGISTRY/NAMESPACE/NAME:TAG.
  2. The token's scope. A read-only token logs in successfully and fails only on push. Compare with the table below.
  3. The registry host. docker login stores credentials per host. Check ~/.docker/config.json for the exact host you push to.
RegistryWhat push needsCommon cause of insufficient_scope
Docker HubA personal access token with Read & Write (or Read, Write, Delete) permission, or your passwordA 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: writeA 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 Registryaz 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 ECRaws ecr get-login-password piped to docker login --username AWS --password-stdin, and IAM permissions for ecr:PutImage and the upload actionsAn 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 authority

The 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.crt

On 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

  • toomanyrequests comes 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 timeout or Client.Timeout exceeded point to the network or a proxy, not to the registry's permissions. Test with curl -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:TAG

8. Rollback and prevention

  • Rollback: docker logout HOST removes a login you added; remove a certs.d folder you created if the CA was wrong.
  • Use a credential helper instead of plain config.json secrets 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

docs.docker.com ↗

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.