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.

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 deniedafter a login attempt means the credentials are present but lack permission: wrong account, expired token, missingread: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 requiredis the registry being explicit that no token arrived.manifest unknownis a different error entirely: the name is wrong or the tag does not exist.
| Message ending | Meaning | First check |
|---|---|---|
repository does not exist or may require 'docker login' | No credentials in this context | docker login in the same shell/CI job |
requested access to the resource is denied | Credentials but no grant | Account, org SSO, token scopes |
manifest unknown | Wrong name or tag | Registry path and tag spelling |
unauthorized | Token missing or expired | Re-authenticate, check clock |
toomanyrequests | Rate limit, not access | Authenticate 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:
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 deniedThe 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:
echo "$REGISTRY_TOKEN" | docker login registry.example.com \
--username "$REGISTRY_USER" --password-stdinKey Comparison Table
The registry decides which credential shape works, and the error text is nearly identical across all of them.
| Registry | Host | Login credential | Scope needed to pull |
|---|---|---|---|
| Docker Hub | docker.io | Account password or PAT | Read on the repository |
| GitHub Container Registry | ghcr.io | PAT or GITHUB_TOKEN | read:packages |
| Amazon ECR | *.dkr.ecr.*.amazonaws.com | aws ecr get-login-password token | ecr:GetDownloadUrlForLayer, BatchGetImage |
| Google Artifact Registry | *.pkg.dev | gcloud auth print-access-token | artifactregistry.reader |
| Azure ACR | *.azurecr.io | ACR token or service principal | AcrPull |
A private image also has to be reachable by whatever runs it, and that is a separate credential store in every orchestrator.
| Runtime | Credential source | Failure symptom |
|---|---|---|
| Local Docker | ~/.docker/config.json | Works in one shell only |
| GitHub Actions | docker/login-action | Later job has no credentials |
| Kubernetes | imagePullSecrets or service account | ImagePullBackOff |
| Docker Compose | Same host config, or credHelpers | Compose runs as another user |
| containerd/nerdctl | ~/.docker/config.json or $DOCKER_CONFIG | Different 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.
docker pull youruser/myapp:latest
docker pull ghcr.io/yourorg/myapp:sha-9f2c1e7An 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.
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 .# syntax=docker/dockerfile:1
FROM yourorg/private-base:22
RUN \
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:
kubectl create secret docker-registry regcred \
--docker-server=ghcr.io \
--docker-username="$GH_USER" \
--docker-password="$GH_TOKEN" \
--namespace=appsapiVersion: v1
kind: Pod
metadata:
name: api
spec:
imagePullSecrets:
- name: regcred
containers:
- name: api
image: ghcr.io/yourorg/api:1.4.0Attaching it to a service account avoids repeating imagePullSecrets on every pod:
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 documentationThe Docker documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit Docker work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Docker guides
All Docker guidesDocker Hub: toomanyrequests and the pull rate limit behind it
Shared CI addresses drain the anonymous quota. Log in, cache the bytes once, and stop pulling production images from Docker Hub.
Docker Compose: dependency failed to start and the health check behind it
The container named in the error is the failing one. Inspect its health log, choose the right condition, and give slow databases a start period.
Docker build: no space left on device while df shows free space
BuildKit cache lives outside docker system df. Measure it with buildx du, prune to a size budget and reorder the Dockerfile.
Docker: Cannot connect to the Docker daemon at unix:///var/run/docker.sock
An endpoint mismatch, a stopped daemon, or a missing socket mount. Resolve which of the three, then start, retarget, or mount.
More in Docker
All Docker guidesThe guides filed next to this one in Docker, in library order.