unauthorized: authentication required (Azure Container Registry push)

unauthorized: authentication required (Azure Container Registry push)

TL;DR

Docker is talking to the registry anonymously. Log in first with az acr login, and if that does not stick, check that the admin user is enabled or use a service principal with pull/push rights. Expired tokens cause this too.

The error

unauthorized: authentication required

(on docker push [registry].azurecr.io/[image] or docker pull.)

Fix it

1. Log in: az acr login --name [registry]. Expected: "Login Succeeded".
2. Retry the push or pull. Expected: it works.
3. If login succeeds but the push still fails, the token may be expiring mid-run. Log in again right before the push. Expected: the push completes.
4. For CI, use a service principal with the AcrPush role instead of the admin user: docker login [registry].azurecr.io -u [app-id] -p [client-secret]. Expected: non-interactive auth works.
5. If you rely on the admin user, confirm it is enabled: registry Settings, Access keys. Expected: the admin user toggle is on and the credentials work.

When to use this

• An agent sees "unauthorized: authentication required" on docker push or pull to ACR.
• CI pipelines that push images to Azure Container Registry.

When NOT to use this

• DNS or network errors reaching the login server. Those fail before auth.
• "repository does not exist" errors. Those are naming problems after successful auth.

Compatibility

• Azure Container Registry, Docker CLI, Azure CLI.

Variant phrasings

• "unauthorized: authentication required"
• "no basic auth credentials" on ACR push

Root cause

ACR rejects anonymous pushes and pulls on private registries. The usual triggers are never having logged in, an expired token from an earlier az acr login, or the admin user being disabled while the pipeline still uses it.

Edge cases

• Tokens from az acr login last about 3 hours. Long builds that push at the end fail with this.
• Private endpoints change nothing about auth. If DNS resolves privately but auth fails, it is still a login problem.