Docker Core
The registry answered with a 401 asking the client to authenticate first.
unauthorized-authentication-requiredReviewed for reference consistency: August 11, 2026
The registry answered with a 401 asking the client to authenticate first.
What unauthorized-authentication-required Means
The unauthorized-authentication-required error on the Docker Core indicates the registry answered with a 401 asking the client to authenticate first.. This typically occurs due to no credential entry exists for this registry host in the client config.
Registry APIs speak token auth: the client fetches a bearer token from an auth service and presents it with each request. When the token is absent, expired, or rejected, the registry returns an unauthorized condition with the authentication required body, and the daemon wraps it in its standard error envelope.
How to fix unauthorized-authentication-required
General informational guidance, not professional advice. Commands can affect your system or data — back up first and proceed at your own risk. FixerCode is an independent reference, not affiliated with any vendor mentioned.
Probe the registry's authentication endpoint
A plain request to the v2 endpoint shows which auth challenge the registry issues before any image metadata moves.
curl -sI https://<registry-host>/v2/Inspect the client's stored auth shape
The parsed config shows auths, credsStore, and credHelpers together, revealing which helper should have produced the missing token.
python3 -c "import json,os;print(json.load(open(os.path.expanduser('~/.docker/config.json'))))"
Technical Background
Authentication-required is the registry speaking protocol, not policy: unlike the access-denied family, it does not judge permissions, it only reports that the caller is anonymous or unverified.
The distinction matters operationally. A fresh login fixes the unauthorized case by producing a token; the denied case can persist with valid credentials when the account simply lacks rights on the namespace.
Common Causes
- No credential entry exists for this registry host in the client config
- The stored token expired and was never refreshed
- The auth service rejected the presented username and secret pair
- A credential helper failed silently, leaving the client without a token
Typical Scenarios
- Pushing to a private registry where the login session aged out mid-pipeline
- A scripted pull against a registry whose anonymous tier is disabled entirely
- An internal mirror requiring credentials the client has not configured
What to Know
The message arrives wrapped in the daemon's error envelope with the registry's own body appended, so the registry host in the URL identifies which credential entry in the client config is the relevant one.
Frequently Asked Questions
Common questions about Docker unauthorized-authentication-required error
Not quite. Unauthorized means the caller presented no acceptable identity; denied means an identity was accepted but lacks the requested right.
In the client config file under the user's Docker directory, optionally delegated to platform credential helpers so raw secrets never sit in the JSON itself.
Related Error Codes
The registry refused the pull because the repository is private or unknown.
The server recognized the caller but refused the specific repository action.
The Hub pull allowance for this address or account ran out inside its window.
Related Errors From Other Categories
Similar error codes documented across different platforms and systems