Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Docker: pull access denied, repository does not exist or may require login

The registry refused the pull for one of five reasons. Separate missing credentials from missing permission, wrong namespace and rate limits.

~5 min readDocker
#Docker#Registries#CI#Kubernetes
A registry tower with a locked repository drawer, an amber denied key plate and a cyan login token

Introduction & Quick Summary

pull access denied for app, repository does not exist or may require 'docker login' is a single message covering several different problems. The registry answered with a 401 or 403 and Docker chose the friendliest wording it had. The image may be private, may not exist under that name, may live under an organisation that requires SSO, or the client may simply not have sent credentials at all.

Read the second half of the message, because it narrows the cause:

  • denied: requested access to the resource is denied after a login attempt means the credentials are present but lack permission: wrong account, expired token, missing read:packages, or SSO not authorised.
  • repository does not exist or may require 'docker login' with no login attempt in the session means the client has no credentials for that registry.
  • unauthorized: authentication required is the registry being explicit that no token arrived.
  • manifest unknown is a different error entirely: the name is wrong or the tag does not exist.
Message endingMeaningFirst check
repository does not exist or may require 'docker login'No credentials in this contextdocker login in the same shell/CI job
requested access to the resource is deniedCredentials but no grantAccount, org SSO, token scopes
manifest unknownWrong name or tagRegistry path and tag spelling
unauthorizedToken missing or expiredRe-authenticate, check clock
toomanyrequestsRate limit, not accessAuthenticate or use a mirror

Core Mechanics, Signatures & Reproducible Setup

Docker resolves an image reference to a registry host, a repository path, and a tag. When the host is omitted, it is Docker Hub, and the repository path must include the namespace: nginx means docker.io/library/nginx, while myapp means docker.io/myapp, which is not the same as docker.io/youruser/myapp. That missing namespace produces "pull access denied" for images that exist.

Credentials come from ~/.docker/config.json, or from $DOCKER_CONFIG when set, and are written by docker login. Each registry has its own auths entry. BuildKit and containerd read the same file, but only when the process can see it, which is why a login in one shell does not help a systemd-run daemon or a nested build.

A reproducible private-repository failure looks like this:

bash
docker login -u "$DOCKERHUB_USER" --password-stdin <<< "$DOCKERHUB_TOKEN" docker pull yourorg/private-app:1.4.0 # works sudo docker pull yourorg/private-app:1.4.0 # pull access denied

The second command fails because sudo starts a new session with a different HOME, so it reads /root/.docker/config.json, which is empty. The same thing happens in CI when a step logs in and a later step runs in a container or as another user.

For anything automated, pass the token on stdin so it never lands in shell history or a layer:

bash
echo "$REGISTRY_TOKEN" | docker login registry.example.com \ --username "$REGISTRY_USER" --password-stdin

Key Comparison Table

The registry decides which credential shape works, and the error text is nearly identical across all of them.

RegistryHostLogin credentialScope needed to pull
Docker Hubdocker.ioAccount password or PATRead on the repository
GitHub Container Registryghcr.ioPAT or GITHUB_TOKENread:packages
Amazon ECR*.dkr.ecr.*.amazonaws.comaws ecr get-login-password tokenecr:GetDownloadUrlForLayer, BatchGetImage
Google Artifact Registry*.pkg.devgcloud auth print-access-tokenartifactregistry.reader
Azure ACR*.azurecr.ioACR token or service principalAcrPull

A private image also has to be reachable by whatever runs it, and that is a separate credential store in every orchestrator.

RuntimeCredential sourceFailure symptom
Local Docker~/.docker/config.jsonWorks in one shell only
GitHub Actionsdocker/login-actionLater job has no credentials
KubernetesimagePullSecrets or service accountImagePullBackOff
Docker ComposeSame host config, or credHelpersCompose runs as another user
containerd/nerdctl~/.docker/config.json or $DOCKER_CONFIGDifferent path than Docker

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

The namespace is missing from the reference

docker pull myapp looks for a Docker Hub official image, not yours. The fix is the fully qualified name, and it is worth writing it everywhere rather than relying on the implicit default.

bash
docker pull youruser/myapp:latest docker pull ghcr.io/yourorg/myapp:sha-9f2c1e7

An image built locally and never pushed produces the same message when someone else pulls it. docker images shows it on the builder; docker manifest inspect youruser/myapp:latest proves whether the registry has it.

BuildKit does not inherit credentials

docker login in your shell does not authenticate a build that pulls a private base image, unless the builder runs with the same config. Pass the config explicitly, or forward a secret to the build step.

bash
DOCKER_BUILDKIT=1 docker build \ --build-arg BASE_IMAGE=yourorg/private-base:22 \ --secret id=dockerconfig,src="$HOME/.docker/config.json" \ -t youruser/app:dev .
dockerfile
# syntax=docker/dockerfile:1 FROM yourorg/private-base:22 RUN --mount=type=secret,id=dockerconfig,target=/root/.docker/config.json \ echo 'credentials mounted for this RUN only'

The --mount=type=secret form keeps the config out of the image layers. A COPY of config.json leaves the credential in the final image, visible to anyone who can pull it.

Kubernetes pulls with its own secret

A pod cannot use your laptop's Docker credentials. It needs an imagePullSecrets entry, or a service account carrying one. The secret is a serialised config.json:

bash
kubectl create secret docker-registry regcred \ --docker-server=ghcr.io \ --docker-username="$GH_USER" \ --docker-password="$GH_TOKEN" \ --namespace=apps
apiVersion: v1 kind: Pod metadata: name: api spec: imagePullSecrets: - name: regcred containers: - name: api image: ghcr.io/yourorg/api:1.4.0

Attaching it to a service account avoids repeating imagePullSecrets on every pod:

bash
kubectl patch serviceaccount default -p '{"imagePullSecrets":[{"name":"regcred"}]}'

A wrong password in regcred produces ImagePullBackOff and the registry's denied message in kubectl describe pod. That message is the same one Docker prints, which is why checking the registry's audit log is often faster than reading the pod events twice.

CI: login, then build, in that order

Each job and each container starts clean. A workflow that builds in job A and pushes in job B needs the login in B as well.

jobs: publish: runs-on: ubuntu-latest permissions: contents: read packages: write steps: - uses: docker/login-action@v3 with: registry: ghcr.io username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} - run: docker pull ghcr.io/${{ github.repository }}/base:latest - run: docker build -t ghcr.io/${{ github.repository }}:${{ github.sha }} . - run: docker push ghcr.io/${{ github.repository }}:${{ github.sha }}

The packages: write permission is easy to miss: with the default GITHUB_TOKEN, a push fails with denied while the pull works only if the package is public.

Rate limits wear the same coat

Docker Hub's anonymous limit answers toomanyrequests, not denied, but a registry mirror in front of it can pass along a denied body when its own upstream credentials are exhausted. If pulls worked an hour ago and fail now across unrelated images, check docker info for the mirror and try the fully qualified docker.io/library/alpine:3.20 reference to see the authentic message.

Common Compilation/Runtime Mistakes & Version Gotchas

Logging in without a registry host. docker login with no argument targets Docker Hub only. GHCR, ECR and ACR each need docker login ghcr.io, aws ecr get-login-password | docker login --username AWS --password-stdin <url>, and so on.

Assuming a password works where a token is required. Docker Hub accounts with 2FA, GHCR and most corporate registries require a personal access token. The error for a password when a token is required is the same denied, so try a token before debugging the repository.

Ignoring SSH versus HTTPS paths on GHCR. ghcr.io/yourorg/app is correct; github.com/yourorg/app is not a registry host, and the resulting error reads like a missing repository.

Using sudo and losing the config. sudo docker reads root's HOME. Either add the user to the docker group, which is the better fix for local work, or copy the config to /root/.docker/config.json for the specific command.

Deleting the image locally to "force a fresh pull". If the reference is wrong, a fresh pull fails the same way. Confirm the reference with docker manifest inspect before pulling again.

Credential helpers that are missing in the image. A config.json with "credHelpers": {"ghcr.io": "desktop"} needs that helper binary. Inside a container it does not exist, so the credential resolves to nothing and the pull is denied. Replace the helper with a static auths entry for CI images, or mount DOCKER_CONFIG.

Version floor. docker login --password-stdin exists in every supported CLI; BuildKit secrets need Dockerfile syntax 1.2 or newer; kubectl create secret docker-registry works on all supported clusters.

The fastest triage is to decide whether the client sent credentials before reading the repository name. When you build a dockerconfigjson secret by hand, the Base64 encoder produces the encoded auth value, and the JSON formatter catches the quoting mistakes that make the secret syntactically valid but unreadable.

Official references: docker login and Docker Hub repositories and access.

Official references

primary documentation

The Docker documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Docker work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Docker guides

More in Docker

All Docker guides

The guides filed next to this one in Docker, in library order.