# 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.