Docker "unexpected status code ... 401/403" from Registry - Fix Auth Flow
The registry returned an auth-related status (401/403) where Docker expected a normal response. Unlike a transient 5xx, this is a deterministic authorization problem in the token-auth handshake.
What this error means
A pull or push fails with received unexpected status code: 401 Unauthorized or 403 Forbidden. It repeats every run - the credential, scope, or auth-endpoint configuration is wrong, not a network blip.
received unexpected HTTP status: 401 Unauthorized
# or during the token exchange:
unexpected status code https://auth.registry/token: 403 ForbiddenCommon causes
Missing or wrong credentials for this registry
No docker login for the host, or credentials for a different registry, so the token-auth challenge cannot be answered with something valid.
Token scope does not cover the requested action
A token valid for pull is used for a push, or it is scoped to a different repository, so the auth server returns 403 for the requested scope.
Misconfigured registry auth endpoint
A self-hosted registry whose Www-Authenticate realm points at a broken or wrong token service returns unexpected statuses during the handshake.
How to fix it
Log in to the exact registry with the right scope
Authenticate to the precise host and use a token that grants the action.
echo "$TOKEN" | docker login registry.example.com -u "$USER" --password-stdin
# push needs a write-scoped token; pull of a private repo needs read scopeInspect the auth handshake
Curl the /v2/ endpoint to see the realm and confirm the token service responds correctly.
curl -i https://registry.example.com/v2/
# follow the Www-Authenticate realm and confirm the token endpoint returns 200 + a tokenHow to prevent it
- Authenticate to each registry host explicitly before pull/push.
- Scope tokens to exactly the actions (read/write) and repos you need.
- For self-hosted registries, verify the token-auth realm is reachable and correct.