🚨 Docker Error Guide: 'pull access denied, repository does not exist or may require docker login'

Overview

Docker prints this when a docker pull (or a build that pulls a base image) cannot access the requested repository:

Error response from daemon: pull access denied for myapp, repository does not exist or may require 'docker login': denied: requested access to the resource is denied

The wording is deliberately ambiguous because the registry cannot tell you the difference between “this repository does not exist” and “it exists but you are not allowed to see it” — revealing which would leak information about private repos. So this single error covers a typo in the image name, a missing registry prefix, a private repo you have not logged into, or a tag that does not exist.

Symptoms

• docker pull myapp:1.4.2 fails immediately with pull access denied for myapp.
• A docker build fails on the FROM line pulling a base image.
• Public images pull fine, but one specific (private or misspelled) image does not.
• The image exists in your registry’s UI but Docker still cannot pull it.

Common Root Causes

• Typo in the image name or namespace — myap instead of myapp, or the wrong org.
• Missing registry prefix — the reference omits registry.example.com/, so Docker looks on Docker Hub where it does not exist.
• Private repository, not logged in — the repo exists but requires authentication you have not provided.
• Tag does not exist — the repository is right but :1.4.2 was never pushed.
• Wrong registry entirely — pulling from Docker Hub when the image lives in a private registry.
• Insufficient permissions — your account cannot read that repository.

Diagnostic Workflow

Read the reference carefully — the first path segment tells Docker which registry to use. No dot/host means Docker Hub:

# myapp:1.4.2                 -> docker.io/library/myapp (Docker Hub official)
# registry.example.com/myteam/myapp:1.4.2  -> your private registry

Confirm whether you are authenticated to the registry the image actually lives in:

cat ~/.docker/config.json      # is registry.example.com under "auths"?
docker login registry.example.com

Verify the repository and tag exist by inspecting the manifest without pulling:

docker manifest inspect registry.example.com/myteam/myapp:1.4.2
docker buildx imagetools inspect registry.example.com/myteam/myapp:1.4.2

If that returns no such manifest the tag is wrong; if it returns unauthorized you need to log in. Then pull with the fully qualified name:

docker pull registry.example.com/myteam/myapp:1.4.2

Example Root Cause Analysis

A new engineer’s build failed on its base image with pull access denied for company-base, repository does not exist or may require 'docker login'. The Dockerfile began with FROM company-base:1.4.2.

Because company-base has no registry host in it, Docker resolved it to docker.io/library/company-base — a public Docker Hub path that does not exist. The image was actually a private base in registry.example.com. Two things were wrong: the missing registry prefix and the missing login.

The fix was to fully qualify the reference and authenticate:

docker login registry.example.com

FROM registry.example.com/myteam/company-base:1.4.2

After qualifying the FROM line and logging in, docker manifest inspect resolved the tag and the build pulled the base image successfully.

Prevention Best Practices

• Always use fully qualified image references (registry/namespace/name:tag) in Dockerfiles, Compose, and manifests so Docker never guesses Docker Hub.
• Add a docker login step before builds that pull private base images, especially in CI.
• Verify tags exist with docker manifest inspect before referencing them in downstream builds.
• Pin explicit tags (avoid latest) so a “missing tag” failure cannot masquerade as an access error.
• Keep base-image names consistent across the team using the Docker stack guide, and lint the FROM lines with the Dockerfile validator.

Quick Command Reference

cat ~/.docker/config.json                                # logged into the right registry?
docker login registry.example.com
docker manifest inspect registry.example.com/myteam/myapp:1.4.2   # repo/tag exist?
docker pull registry.example.com/myteam/myapp:1.4.2      # fully qualified name

Conclusion

This error deliberately blurs “does not exist” and “you cannot see it,” so work through both. Check the image reference for typos and a missing registry host — a bare name defaults to Docker Hub. Then confirm you are logged into the registry that actually holds the image and that the tag exists via docker manifest inspect. Fully qualify every reference and add a login step for private repos, and the pull will resolve cleanly.