How to fix pull access denied, repository does not exist or may require authentication in Docker

DockerBEGINNERMEDIUMUpdated Dec 6, 2025· 677 views

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.

Quick fix

Fixes pull access denied, repository does not exist or may require authentication

# 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 -> ubuntu

Double-check the image name spelling
Verify the image and tag exist on the registry
Log in to Docker Hub or your private registry
Use the fully qualified image name

docker — error

$# 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 -> ubuntu
pull access denied, repository does not exist or may require authentication

What this error means

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.

Typical symptoms

Docker pull command fails with 'pull access denied' message
Docker run fails to start a container because the image cannot be pulled
Docker Compose fails during the pull phase with this error
Dockerfile build fails on FROM instruction when base image cannot be pulled
CI/CD pipelines fail at the image pull step
Error message suggests running 'docker login' even for public images

Common causes

Typo in the image name (e.g., 'ngnix' instead of 'nginx' or 'pyhon' instead of 'python')
Missing or incorrect namespace in the image path
Referencing a non-existent image tag
Repository is private and you are not logged in
Using sudo for docker commands but not for docker login
Docker Hub rate limit exceeded for anonymous users
Image was deleted or renamed on the registry
Wrong registry specified for the image
Credential helper issues preventing authentication

How to fix "pull access denied, repository does not exist or may require authentication"

1Double-check the image name spelling

The most common cause is a simple typo. Verify the exact image name on Docker Hub or your registry.

bash

# 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 -> ubuntu

Visit [Docker Hub](https://hub.docker.com) and search for the image to confirm the exact name and available tags.

2Verify the image and tag exist on the registry

Check that both the repository and the specific tag you're requesting actually exist.

bash

# 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:latest

For official images, the full path is docker.io/library/IMAGE:TAG. For user repositories, it's docker.io/USERNAME/IMAGE:TAG.

3Log in to Docker Hub or your private registry

If the repository is private or you're hitting rate limits, authenticate with the registry:

bash

# 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.com

Important: If you use sudo for Docker commands, you must also use sudo for login:

bash

sudo docker login
sudo docker pull myimage:tag

4Use the fully qualified image name

Specify the complete image path including registry, namespace, and tag:

bash

# 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.0

This eliminates ambiguity about which registry and namespace to use.

5Check and reset Docker credentials

If you're logged in but still getting denied, your stored credentials may be corrupted or outdated:

bash

# 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.json

On Linux, credentials are stored in ~/.docker/config.json. On macOS, they're in the Keychain. On Windows, they're in the Windows Credential Manager.

6Check Docker Hub rate limits

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:

bash

# 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 ratelimit

If rate limited, authenticate with docker login to get higher limits, or wait for the limit to reset.

Advanced notes

### Understanding Image Naming

Docker image names follow this format:

bash

[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:

bash

# 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:

dockerfile

# This will fail if mybase doesn't exist
FROM mybase:latest

Ensure 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:

yaml

# 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:

bash

# 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-world

Frequently asked questions

What does "pull access denied, repository does not exist or may require authentic" mean?: 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.
How do I fix "pull access denied, repository does not exist or may require authentic"?: 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.
What causes "pull access denied, repository does not exist or may require authentic"?: Typo in the image name (e.g., 'ngnix' instead of 'nginx' or 'pyhon' instead of 'python') Missing or incorrect namespace in the image path Referencing a non-existent image tag
Is the "pull access denied, repository does not exist or may require authentic" error serious?: It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading

📚Docker Official Documentation
📖
Docker pull command reference(Official Docs)
💬
Stack Overflow - Pull access denied(Stack Overflow)
📖
LabEx - How to resolve pull access denied error(Official Docs)
💬
Docker Forums - Pull access denied discussion(Stack Overflow)
📝
100 Common Docker Errors & Solutions

How to fix pull access denied, repository does not exist or may require authentication in Docker

Quick fix

What this error means

Typical symptoms

Common causes

How to fix "pull access denied, repository does not exist or may require authentication"

Advanced notes

Frequently asked questions

Related errors

Official resources & further reading