The 'repository not found: does not exist or no pull access' error occurs when Docker cannot locate the specified image repository on the registry. This typically happens due to an incorrect repository name, the repository not existing, or lacking authentication for a private repository.
This error indicates that the Docker daemon could not find the specified repository on the container registry. When you run a `docker pull` command (or any command that implicitly pulls an image like `docker run`), Docker contacts the registry to download the image layers. This error appears when the registry returns a "not found" response. The error message "does not exist or no pull access" covers two distinct scenarios: 1. **The repository genuinely does not exist** - The image name is misspelled, the repository was deleted, or it was never pushed to the registry in the first place. 2. **The repository exists but is private** - Private repositories require authentication before Docker can access them. Without proper credentials, the registry responds with the same "not found" error for security reasons (to avoid revealing whether private repositories exist). This is different from similar errors like "pull access denied" or "manifest not found" - this error specifically indicates the repository path itself cannot be located or accessed.
First, confirm that the repository name is spelled correctly and follows the correct format for your registry.
# Docker Hub format: username/repository:tag
docker pull myusername/myimage:latest
# Private registry format: registry.example.com/repository:tag
docker pull registry.example.com/myproject/myimage:v1.0Double-check for common mistakes:
- Typos in the repository or organization name
- Incorrect capitalization (repository names are case-sensitive)
- Missing namespace (e.g., myimage instead of myusername/myimage)
You can search for the image on Docker Hub:
docker search myimageOr verify the repository exists by visiting it in a browser:
- Docker Hub: https://hub.docker.com/r/username/repository
If the repository is private, you must log in before pulling:
# Log in to Docker Hub
docker login
# Log in to a private registry
docker login myregistry.example.com
# Log in to a specific registry with username
docker login -u myusername myregistry.example.comImportant considerations:
- If you use sudo for Docker commands, you must also run sudo docker login
- Credentials are stored in ~/.docker/config.json (or /root/.docker/config.json for sudo)
- Some registries require access tokens instead of passwords
For cloud provider registries:
# AWS ECR
aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-west-2.amazonaws.com
# Google Container Registry
gcloud auth configure-docker
# Azure Container Registry
az acr login --name myregistryAlways use the complete image path including the registry domain when pulling from non-Docker Hub registries:
# Docker Hub (docker.io is implicit)
docker pull docker.io/library/nginx:latest
docker pull docker.io/myusername/myimage:tag
# Private registry - include full URL
docker pull myregistry.example.com/myproject/myimage:v1.0
# Registry with custom port
docker pull registry.example.com:5000/myimage:tagCommon registry URLs:
- Docker Hub: docker.io (default, can be omitted)
- GitHub Container Registry: ghcr.io
- Google Container Registry: gcr.io
- Amazon ECR: <account-id>.dkr.ecr.<region>.amazonaws.com
- Azure Container Registry: <registry-name>.azurecr.io
Verify the repository actually exists on your target registry:
For Docker Hub:
# Use Docker Hub API to check if repository exists
curl -s "https://hub.docker.com/v2/repositories/username/repository/" | jq '.name'For private registries with V2 API:
# List available tags (requires authentication for private repos)
curl -s "https://myregistry.example.com/v2/myimage/tags/list"If the repository doesn't exist, you need to:
1. Push the image to the registry first, or
2. Use a different, existing image, or
3. Build the image locally if you have the Dockerfile
If you need to create the repository by pushing an image:
# Build the image locally
docker build -t myregistry.example.com/myproject/myimage:v1.0 .
# Log in to the registry
docker login myregistry.example.com
# Push the image (this creates the repository if it doesn't exist)
docker push myregistry.example.com/myproject/myimage:v1.0For Docker Hub:
# Build and tag for Docker Hub
docker build -t myusername/myimage:latest .
# Log in and push
docker login
docker push myusername/myimage:latestNote: Some registries require you to create the repository through their web interface before you can push to it.
If authentication seems correct but still fails, try resetting your credentials:
# Log out from the registry
docker logout myregistry.example.com
# Or log out from Docker Hub
docker logout
# Remove cached credentials (backup first)
mv ~/.docker/config.json ~/.docker/config.json.backup
# Log in again fresh
docker login myregistry.example.comThis clears any stale or corrupted credentials that might be causing authentication to silently fail.
### Understanding Registry Authentication Behavior
For security reasons, private registries typically respond with "repository not found" rather than "access denied" when an unauthenticated user tries to access a private repository. This prevents attackers from enumerating which private repositories exist. If you're certain the repository exists, the issue is almost always authentication.
### Multi-Architecture Images
When pulling images on different architectures (ARM64 vs AMD64), the repository might exist but not have a manifest for your specific architecture:
# Check available platforms for an image
docker manifest inspect myregistry/myimage:tag### Mirror and Cache Considerations
If you're using a registry mirror or pull-through cache, the "repository not found" error might indicate:
- The mirror hasn't cached the image yet
- The upstream registry is unreachable
- The mirror's credentials for the upstream registry are invalid
# Check if Docker is configured to use a mirror
cat /etc/docker/daemon.json | jq '.registry-mirrors'### Kubernetes and Container Orchestration
In Kubernetes, this error often appears in pod events. Ensure:
1. ImagePullSecrets are correctly configured
2. Service accounts have the correct secret attached
3. The secret contains valid credentials for the registry
# Check pod events for pull errors
kubectl describe pod mypod | grep -A5 "Events:"
# Verify image pull secret exists
kubectl get secret myregistry-secret -o yaml### Registry Hostname Resolution
Ensure the registry hostname resolves correctly:
# Test DNS resolution
nslookup myregistry.example.com
# Test HTTPS connectivity
curl -v https://myregistry.example.com/v2/### Debug Mode
Run Docker in debug mode to get more detailed error information:
# One-time debug pull
DOCKER_CLI_DEBUG=1 docker pull myregistry.example.com/myimage:tagimage 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