🐳 Docker Error Guide: 'unauthorized: authentication required' Registry Token Failure

Exact Error Message

Error response from daemon: pull access denied for registry.example.com/team/api,
repository does not exist or may require 'docker login':
denied: requested access to the resource is denied

On a push, or when the token exchange itself fails, you will typically see:

unauthorized: authentication required

Both are token-based authentication failures: the registry’s token endpoint refused to issue a token with the scope your operation needs.

What It Means

Docker registries use the OAuth2-style token authentication flow defined by the Distribution spec. When you pull or push, the daemon first hits the registry, receives a 401 with a WWW-Authenticate header naming a token endpoint, service, and required scope (for example repository:team/api:pull,push). The daemon then requests a bearer token for that scope from the token endpoint using your credentials, and retries the original request with the token.

unauthorized: authentication required means that exchange failed. Either no credentials were sent, the credentials were wrong or expired, the account lacks permission for the requested scope, or the token endpoint could not be reached correctly. It is an authorization/scope problem, not a networking or image-not-found problem, even though the “repository does not exist” wording can be misleading.

Common Causes

• You are not logged in to that registry, or the login was to a different hostname.
• The stored token or credential expired (short-lived registry tokens, rotated PATs, expired cloud login).
• The account or token has read access but you are pushing, so the push scope is denied.
• Wrong registry hostname or a missing project/namespace in the image reference.
• A broken or empty credential store / credsStore helper that returns no credentials.
• CI uses a robot account that lacks permission on the target repository.

Diagnostic Commands

Confirm which registries you are logged in to and how credentials are stored:

cat ~/.docker/config.json

Log in explicitly to the exact registry host in the image reference:

docker login registry.example.com

Reproduce the failing operation with verbose daemon-side detail (check journalctl -u docker after):

docker pull registry.example.com/team/api:latest

Inspect the challenge the registry issues, which reveals the token endpoint and required scope:

curl -sI https://registry.example.com/v2/team/api/manifests/latest | grep -i www-authenticate

Step-by-Step Resolution

1. Log in to the precise hostname in your image tag. docker.io credentials do not authorize registry.example.com, and vice versa:

docker login registry.example.com

2. Verify the image reference includes the full registry host and namespace. A missing project segment causes a scope the token cannot cover:

docker pull registry.example.com/team/api:1.4.0

3. If pulling works but pushing fails, the problem is scope. Confirm the account has write permission on that repository, then retry the push:

docker push registry.example.com/team/api:1.4.0

4. Clear stale credentials and re-authenticate when a token or PAT has expired or rotated:

docker logout registry.example.com
docker login registry.example.com -u ci-robot --password-stdin < token.txt

5. Fix a broken credential helper. If credsStore points at a helper that is not installed, logins silently store nothing. Remove or correct it in ~/.docker/config.json:

{
  "auths": {},
  "credsStore": "desktop"
}

6. In CI, log in non-interactively with a scoped robot token before the pull/push step:

echo "$REGISTRY_TOKEN" | docker login registry.example.com -u "$REGISTRY_USER" --password-stdin

7. Retry the operation and confirm success:

docker push registry.example.com/team/api:1.4.0

1.4.0: digest: sha256:9f2a... size: 1996

Prevention

• Always tag and log in with the fully qualified registry hostname so the token scope matches the request.
• Use scoped robot/service accounts in CI, and confirm they have push (not just pull) where needed.
• Rotate and store registry tokens as secrets; feed them via --password-stdin, never on the command line.
• Verify your credential helper (credsStore) is actually installed, or logins will store nothing.
• Treat short-lived cloud registry logins (ECR, GAR, ACR) as expiring; re-run their login command in each pipeline. For generating registry login and push steps, see the DevOps AI prompt library.

Related Errors

• denied: requested access to the resource is denied — the push-scope refusal, usually missing write permission.
• pull access denied ... repository does not exist or may require 'docker login' — unauthenticated or wrong-host pull.
• error getting credentials - err: exec: "docker-credential-desktop": executable file not found — a broken credential helper.
• no basic auth credentials — no stored credentials for that registry at all.

Frequently Asked Questions

Why does it say the repository does not exist when I know it does? Registries return a generic “does not exist or may require docker login” message for both missing repos and permission denials, to avoid leaking whether private repos exist. Log in with the correct host and namespace and retry.

I can pull but not push. Why? Pull and push require different token scopes. Your account or robot token has read access but lacks write permission on that repository. Grant push access or use a credentialed account that has it.

Why do I get this only in CI, not locally? Locally your docker login credentials are cached; CI starts clean. Add a non-interactive docker login ... --password-stdin step with a scoped token before the pull or push.

My login succeeds but the next command still fails. A misconfigured credsStore in ~/.docker/config.json can accept the login yet store nothing. Verify the helper is installed, or remove credsStore to fall back to plaintext auth. For more, see the Docker guides.