Container Registry errors

First run az acr check-health -n <registry> --yes: it checks the local Docker client, DNS and the registry's endpoints, and names the step that fails. Registry facts that decide most failures: admin user off by default, anonymous pull off, public network access on, and a role assignment mode that is either legacy (LegacyRegistryPermissions, the API default) or ABAC (AbacRepositoryPermissions).

Which role to grant

Registry mode (`az acr show -n <acr> --query roleAssignmentMode -o tsv`)	Pull	Push	Delete
`LegacyRegistryPermissions` (portal: RBAC Registry Permissions)	AcrPull	AcrPush	AcrDelete
`AbacRepositoryPermissions` (RBAC Registry + ABAC Repository Permissions)	Container Registry Repository Reader	Container Registry Repository Writer	Container Registry Repository Contributor

In ABAC mode, AcrPull, AcrPush and AcrDelete are not honored, and ACR Tasks and quick builds lose their default data-plane access. Switching an existing registry to ABAC mode without assigning the new roles first cuts off every existing identity. The ABAC roles can carry a condition limiting them to repositories or prefixes; a condition that doesn't match the full repository name denies it.

Authentication

Message	Cause → fix	Check
`unauthorized: authentication required, visit https://aka.ms/acr/authorization for more information.` (also `{"errors":[{"code":"UNAUTHORIZED",…}]}`)	No credential, a wrong or regenerated admin password, an expired service principal secret or token password, a disabled admin account or token, or an Entra identity that can't get an ACR token. Docker can keep sending a stale cached credential: `docker logout <acr>.azurecr.io`, then sign in again	`az acr login -n <acr>`; for a service principal, `az ad app credential list --id <app-id> --query "[].endDateTime" -o tsv`
`DOCKER_COMMAND_ERROR Please verify if Docker client is installed and running`, or Cloud Shell's `This command requires running the docker daemon …`	`az acr login` needs a Docker daemon. Use `az acr login -n <acr> --expose-token` and pass the token to your tool	—
`CONNECTIVITY_REFRESH_TOKEN_ERROR` … `Response code: 401` and `Unable to get admin user credentials …`	The signed-in identity can't see the registry or lacks a role: sign in to the right tenant and subscription, grant a role	`az acr show -n <acr>`

Authorization and registry state

Message	Cause → fix	Check
`insufficient_scope: authorization failed`	The identity can sign in but lacks the push (or pull) role for the registry's mode (table above), an ABAC condition doesn't match the repository, or a repository token's scope map lacks `content/read` / `content/write`	`az role assignment list --assignee <principal-id> --scope <registry-id> --include-inherited -o table`
`The operation is disallowed on this Azure Container Registry, repository, or image. …`	The repository or image is locked (`writeEnabled: false` or `deleteEnabled: false`), or the registry hit its storage limit	`az acr repository show -n <acr> --repository <repo>` (look at `changeableAttributes`)
`manifest unknown: manifest tagged by "<tag>" is not found`	The tag doesn't exist in that repository	`az acr repository show-tags -n <acr> --repository <repo> -o tsv`
`MANIFEST_INVALID: manifest invalid`	Manifest too large or malformed	Rebuild and push with a current client
`Access to Key Encryption Key is forbidden. …` / `CMK_ERROR` / `The identity associated with the registry is inactive. …`	Customer-managed key: the registry's identity lost Key Vault access or was removed	`reference/keyvault/access-and-errors.md`
`429 Too Many Requests` / `TOOMANYREQUESTS: too many requests`	Throttling from too many concurrent requests: retry with backoff and reduce parallelism. Throughput limits differ by SKU; read them on the SKU page, don't assume	—

Network

Message	Cause → fix	Check
`denied: {"errors":[{"code":"DENIED","message":"client with IP '<ip>' is not allowed access. Refer https://aka.ms/acr/firewall to grant access."}]}`	The registry firewall. For App Service, the app's outbound IPs; better, a private endpoint and VNet integration (or VNet-integrated Container Apps)	`az acr show -n <acr> --query "{public:publicNetworkAccess, rules:networkRuleSet}"`
`<acr>.azurecr.io` resolves to a public IP although the registry has a private endpoint	The private DNS zone `privatelink.azurecr.io` isn't linked to the client's VNet, or a custom DNS server doesn't forward to Azure DNS (`168.63.129.16`). With a private endpoint the registry also gets dedicated data endpoints (`<acr>.<region>.data.azurecr.io`, one per geo-replica) that must resolve privately too	`nslookup <acr>.azurecr.io` from the client
`Get "https://<acr>.azurecr.io/v2/": net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)`	DNS, route, firewall or proxy between client and registry	`az acr check-health`
`dial tcp: lookup <acr>.azurecr.io: no such host`	Wrong login server name, or DNS	The login server: `az acr show -n <acr> --query loginServer -o tsv`
`x509: certificate signed by unknown authority` / `proxyconnect tcp: …`	A TLS-inspecting proxy whose CA the client doesn't trust, or a wrong proxy setting	Client proxy and trust store
`invalid reference format: repository name must be lowercase`	Image references must be lowercase	The image string

Pulls from each service: reference/app-service/errors.md, reference/container-apps/errors.md, reference/container-instances/errors.md.