--- cuppy_hub: azure cuppy_path: reference/container-registry/errors.md cuppy_section: docs cuppy_doc: NFJ8-1YK4 cuppy_doc_uuid: 808e901d-c5f7-45bd-92b9-fbf9dbd288b3 cuppy_permalink: https://cuppy.io/azure/d/NFJ8-1YK4 cuppy_version: 1 cuppy_updated: 2026-10-23T16:16:52.575Z cuppy_canonical: https://cuppy.io/azure/docs/reference/container-registry/errors cuppy_mcp: https://cuppy.io/mcp cuppy_body_sha256: 65172067ea715d09522b470086a20aafb0ff5f048c6796e951af25b9e4492cda # cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks. --- # Container Registry errors **First run `az acr check-health -n --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 --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 .azurecr.io`, then sign in again | `az acr login -n `; for a service principal, `az ad app credential list --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 --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 ` | ## 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 --scope --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 --repository ` (look at `changeableAttributes`) | | `manifest unknown: manifest tagged by "" is not found` | The tag doesn't exist in that repository | `az acr repository show-tags -n --repository -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 '' 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 --query "{public:publicNetworkAccess, rules:networkRuleSet}"` | | `.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** (`..data.azurecr.io`, one per geo-replica) that must resolve privately too | `nslookup .azurecr.io` from the client | | `Get "https://.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 .azurecr.io: no such host` | Wrong login server name, or DNS | The login server: `az acr show -n --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`. --- You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 107 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/azure/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.