Introduction
The error Failed to pull image: pull access denied, repository does not exist or may require 'docker login' means Docker cannot find or access the image you requested. The three most common causes are a typo in the image name, a private registry that requires authentication, or a missing tag that defaults to latest which does not exist. The fix depends on which of these applies.
The Error
1docker pull mycompany/myapp:v2.1
2# Error response from daemon: pull access denied for mycompany/myapp,
3# repository does not exist or may require 'docker login': denied:
4# requested access to the resource is denied
This same error appears when running docker run, docker-compose up, or deploying to Kubernetes — any operation that triggers an image pull.
Cause 1: Typo in Image Name
The most frequent cause. Docker image names are case-sensitive and must match exactly:
1# WRONG — typo in image name
2docker pull ngingx # should be nginx
3docker pull postgress # should be postgres
4docker pull mycompany/my-app # maybe it's mycompany/myapp (no hyphen)
5
6# CORRECT
7docker pull nginx
8docker pull postgres
9
10# Verify the image exists on Docker Hub
11docker search nginx
For private registries, include the full registry URL:
1# WRONG — missing registry prefix
2docker pull myapp:latest
3
4# CORRECT — full registry path
5docker pull registry.example.com/myapp:latest
6docker pull ghcr.io/myorg/myapp:latest
7docker pull 123456789.dkr.ecr.us-east-1.amazonaws.com/myapp:latest
Cause 2: Private Repository Requires Authentication
1# Login to Docker Hub
2docker login
3# Username: myuser
4# Password: ********
5# Login Succeeded
6
7# Login to a private registry
8docker login registry.example.com
9
10# Login to GitHub Container Registry
11echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin
12
13# Login to AWS ECR
14aws ecr get-login-password --region us-east-1 | \
15 docker login --username AWS --password-stdin 123456789.dkr.ecr.us-east-1.amazonaws.com
16
17# Login to Google Container Registry
18gcloud auth configure-docker
After logging in, retry the pull:
docker pull mycompany/private-app:latest
Cause 3: Tag Does Not Exist
1# The image exists but the tag doesn't
2docker pull nginx:v99 # No such tag
3docker pull nginx:latest # Works — 'latest' exists for nginx
4
5# Check available tags on Docker Hub
6# Visit https://hub.docker.com/_/nginx/tags
7# Or use the registry API:
8curl -s "https://registry.hub.docker.com/v2/repositories/library/nginx/tags/?page_size=10" | \
9 python3 -c "import sys,json; [print(t['name']) for t in json.load(sys.stdin)['results']]"
Fix for Kubernetes Deployments
Kubernetes needs credentials stored as a Secret to pull from private registries:
1# Create an image pull secret
2kubectl create secret docker-registry my-registry-secret \
3 --docker-server=registry.example.com \
4 --docker-username=myuser \
5 --docker-password=mypassword \
6 --docker-email=[email protected]
7
8# Reference it in the pod spec
1apiVersion: v1
2kind: Pod
3metadata:
4 name: myapp
5spec:
6 containers:
7 - name: myapp
8 image: registry.example.com/myapp:v2.1
9 imagePullSecrets:
10 - name: my-registry-secret
Fix for Docker Compose
1# docker-compose.yml
2services:
3 app:
4 image: registry.example.com/myapp:v2.1
5 # Login to the registry before running docker-compose up
6
7 # Or build locally instead of pulling
8 app-local:
9 build:
10 context: .
11 dockerfile: Dockerfile
# Login first, then compose
docker login registry.example.com
docker-compose up
Fix for GitHub Actions / CI
1# .github/workflows/deploy.yml
2jobs:
3 deploy:
4 steps:
5 - name: Login to Docker Hub
6 uses: docker/login-action@v3
7 with:
8 username: ${{ secrets.DOCKERHUB_USERNAME }}
9 password: ${{ secrets.DOCKERHUB_TOKEN }}
10
11 - name: Pull and deploy
12 run: docker pull mycompany/myapp:latest
Debugging Steps
1# 1. Check if you're logged in
2docker info | grep Username
3
4# 2. Verify the image name and tag exist
5docker manifest inspect mycompany/myapp:v2.1
6
7# 3. Check your credentials file
8cat ~/.docker/config.json
9
10# 4. Test with a known public image
11docker pull hello-world
12
13# 5. Check Docker daemon logs
14journalctl -u docker.service --since "5 minutes ago"
15
16# 6. Test network connectivity to the registry
17curl -v https://registry.example.com/v2/
Common Pitfalls
Expired credentials: Docker login tokens expire. Re-run docker login if pulls that previously worked start failing. AWS ECR tokens expire after 12 hours.
Wrong registry URL: docker.io (Docker Hub) is the default. If your image is on ghcr.io, quay.io, or a private registry, you must include the full URL in the image name.
Missing library/ prefix: Official Docker Hub images like nginx are actually library/nginx. Custom user images need the username prefix: myuser/myimage.
Rate limiting: Docker Hub limits anonymous pulls to 100 per 6 hours and authenticated pulls to 200. Exceeded limits return a similar access denied error. Authenticate to increase the limit.
Kubernetes imagePullPolicy: Always: If set, Kubernetes tries to pull on every pod start. If the registry is temporarily unavailable, pods fail to start even if the image is cached locally. Use IfNotPresent for stability.
Summary
The error means Docker cannot find or access the requested image
Check for typos in the image name, tag, and registry URL first
Use docker login to authenticate with private registries
For Kubernetes, create an imagePullSecret and reference it in the pod spec
Use docker manifest inspect to verify an image exists before deploying
CI/CD pipelines need explicit login steps before pulling private images
