What does docker:unauthorized_authentication_required mean?

Docker registry authentication failed because no valid credentials were sent, so you need to log in or fix the token used for that registry.

unauthorized: authentication required

Q: How do I prevent docker:unauthorized_authentication_required in CI?

Keep registry hostnames explicit in scripts instead of relying on ambiguous defaults. Use automation tokens for CI and rotate them regularly. Document which credential helper or secret source each environment uses.

Fix it fast

Most likely: Docker did not send valid credentials for the exact registry host in the image reference.

1. Confirm this is your error

unauthorized: authentication required

2. Check the cause

printf '%s\n' '<registry>/<namespace>/<repository>:<tag>'
docker logout <registry>
docker login <registry>
docker manifest inspect <registry>/<namespace>/<repository>:<tag>

3. Apply the safe fix

# Log in to the same registry host used by the image reference.
docker login <registry>
docker pull <registry>/<namespace>/<repository>:<tag>

# In CI, make sure the login step runs before pull or push and that the secret is not empty.

4. Verify it works

docker manifest inspect <registry>/<namespace>/<repository>:<tag>
docker pull <registry>/<namespace>/<repository>:<tag>

Don't use unsafe shortcuts

Do not log in to Docker Hub if the image reference points to GHCR, ECR, GCR, or another private registry.
Do not print registry passwords or tokens while checking CI variables.
Do not debug image tags before confirming credentials are available for the registry host.

What Access Failed

This is usually a target-and-identity problem, not a syntax problem. The request made it to the server, but the server did not like the credentials, permissions, or repository path attached to it.

Fix credentials and target access

Login to the exact registry host shown in the image reference:docker login <registry>

If this happens in CI, print the registry host and confirm the secret variables are present before the login step.

If you use a cloud registry, fetch a fresh short-lived token and retry the login.

If credentials are stored locally, run docker logout <registry> and then log in again so Docker refreshes the stored credential.

Manual authentication checks

Print the exact registry host from the image reference.

Check ~/.docker/config.json and confirm the host is covered by either auths or your configured credential helper.

If CI is involved, confirm the login step actually ran before the failing pull or push.

Why It Happens

Usually this comes down to you are not logged in to the target registry host, CI did not inject the expected token or password into docker login, or the credential helper is not returning credentials for the registry you are talking to.

Prove the Failing Environment Can Reach It

Retry the pull or push and confirm the registry no longer returns authentication required, and run a simple authenticated operation against the same registry and repository path.

How registry authentication works

Docker sends registry credentials based on the registry host in the image reference. If no valid credentials are available for that host, the registry rejects the request before Docker can read manifests or layers.

Keep Credentials and Targets Aligned

To prevent this, keep registry hostnames explicit in scripts instead of relying on ambiguous defaults, use automation tokens for CI and rotate them regularly, and document which credential helper or secret source each environment uses.