The 'pull access denied, repository does not exist or may require authentication' error occurs when Docker cannot locate or access an image from the registry. This is commonly caused by typos in the image name, missing authentication for private repositories, or referencing images that don't exist.
This error indicates that the Docker daemon cannot pull the requested image from the container registry. The error message combines two possible scenarios: 1. **Repository does not exist**: The image name, namespace, or tag you specified doesn't exist on the registry. This could be due to a typo, incorrect namespace, or the image simply not being published. 2. **May require authentication**: The repository exists but is private, requiring you to log in before pulling. Docker Hub and other registries allow users to create private repositories that are only accessible to authenticated users. The Docker daemon first checks if the image exists locally. If not found, it attempts to pull from Docker Hub (the default registry) or a specified private registry. When the registry returns an access denied response, Docker displays this error. This is one of the most common Docker errors, especially for beginners who may not realize that some images require authentication or that their image name contains a typo.
The most common cause is a simple typo. Verify the exact image name on Docker Hub or your registry.
# Search Docker Hub for the correct image name
docker search nginx
# Common misspellings to watch for:
# - ngnix -> nginx
# - mongodb -> mongo
# - postgress -> postgres
# - pyhon -> python
# - ubunut -> ubuntuVisit [Docker Hub](https://hub.docker.com) and search for the image to confirm the exact name and available tags.
Check that both the repository and the specific tag you're requesting actually exist.
# List available tags for an image using the Docker Hub API
curl -s "https://hub.docker.com/v2/repositories/library/nginx/tags?page_size=10" | jq '.results[].name'
# Or check the full manifest to see if an image exists
docker manifest inspect nginx:latestFor official images, the full path is docker.io/library/IMAGE:TAG. For user repositories, it's docker.io/USERNAME/IMAGE:TAG.
If the repository is private or you're hitting rate limits, authenticate with the registry:
# Log in to Docker Hub
docker login
# Log in to a specific registry
docker login registry.example.com
# Log in to GitHub Container Registry
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin
# Log in to AWS ECR
aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin 123456789.dkr.ecr.us-west-2.amazonaws.comImportant: If you use sudo for Docker commands, you must also use sudo for login:
sudo docker login
sudo docker pull myimage:tagSpecify the complete image path including registry, namespace, and tag:
# Instead of just:
docker pull myapp
# Use the full path:
docker pull docker.io/myusername/myapp:latest
# For official images:
docker pull docker.io/library/nginx:1.25
# For private registries:
docker pull registry.example.com:5000/myproject/myapp:v1.0This eliminates ambiguity about which registry and namespace to use.
If you're logged in but still getting denied, your stored credentials may be corrupted or outdated:
# Check current credential configuration
cat ~/.docker/config.json
# Log out and log back in
docker logout
docker login
# If using a credential helper and having issues, temporarily disable it
# by removing the "credsStore" line from ~/.docker/config.jsonOn Linux, credentials are stored in ~/.docker/config.json. On macOS, they're in the Keychain. On Windows, they're in the Windows Credential Manager.
Docker Hub limits pulls for free and anonymous users:
- Anonymous: 100 pulls per 6 hours per IP
- Authenticated free: 200 pulls per 6 hours
- Pro/Team/Business: Higher or unlimited
Check your current rate limit status:
# Get a token and check remaining pulls
TOKEN=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:library/alpine:pull" | jq -r .token)
curl -sI -H "Authorization: Bearer $TOKEN" \
https://registry-1.docker.io/v2/library/alpine/manifests/latest \
| grep -i ratelimitIf rate limited, authenticate with docker login to get higher limits, or wait for the limit to reset.
### Understanding Image Naming
Docker image names follow this format:
[REGISTRY/][NAMESPACE/]REPOSITORY[:TAG]- REGISTRY: Defaults to docker.io (Docker Hub)
- NAMESPACE: For Docker Hub, official images use library, user images use the username
- REPOSITORY: The image name
- TAG: Defaults to latest if not specified
### Private Registry Authentication
For registries other than Docker Hub, include the full registry URL when logging in:
# Azure Container Registry
az acr login --name myregistry
# Google Container Registry
gcloud auth configure-docker
# AWS ECR
aws ecr get-login-password | docker login --username AWS --password-stdin <account>.dkr.ecr.<region>.amazonaws.com### Dockerfile Base Image Issues
When this error occurs during docker build on the FROM instruction:
# This will fail if mybase doesn't exist
FROM mybase:latestEnsure the base image is either:
1. A valid public image on Docker Hub
2. A private image you're authenticated to pull
3. A local image that exists on your system (build it first)
### CI/CD Best Practices
In CI/CD environments, always authenticate before pulling:
# GitHub Actions
- name: Login to Docker Hub
uses: docker/login-action@v3
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
# GitLab CI
before_script:
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY### Debugging Steps
If the issue persists:
# Check Docker daemon logs
sudo journalctl -u docker.service --since "1 hour ago" | tail -n 50
# Verify network connectivity to the registry
curl -v https://registry-1.docker.io/v2/
# Test with a known working image
docker pull hello-worldimage operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker
cannot open '/etc/passwd': Permission denied
How to fix 'cannot open: Permission denied' in Docker
Error response from daemon: failed to create the ipvlan port
How to fix 'failed to create the ipvlan port' in Docker
toomanyrequests: Rate exceeded for anonymous users
How to fix 'Rate exceeded for anonymous users' in Docker Hub