How to Fix Azure Container Registry Errors

This is the boring first step that everyone skips, and then wastes 40 minutes on. Check it first.

az --version

You need version 2.0.55 or later. If you're below that, the az acr sub-commands may be incomplete or missing entirely, which produces errors that look exactly like authentication failures but aren't. Update with:

# Windows (via MSI installer, reopen terminal after)
az upgrade

# Or on Windows via winget
winget upgrade Microsoft.AzureCLI

Once you've confirmed your CLI version, run the health check against your specific registry:

az acr check-health --name YOUR_REGISTRY_NAME --yes

The --yes flag skips the interactive confirmation prompt, which matters in scripts. This command will output a table of checks. Look specifically for:

• DOCKER_PULL_ERROR, Docker isn't running or can't pull the hello-world test image
• CONNECTIVITY_DNS_ERROR, DNS can't resolve your registry's hostname
• CONNECTIVITY_ENDPOINT_ERROR, The registry endpoint is unreachable (firewall or private endpoint issue)
• HELM_VERSION_ERROR, Only matters if you're storing Helm charts

If the health check shows green across the board but you still can't push, the problem is definitively RBAC. Move to Step 3. If you see CONNECTIVITY_DNS_ERROR, your machine can't resolve the Azure Container Registry endpoint, that's a local DNS or VPN issue, and Step 4 covers it. If Docker shows errors, make sure the Docker daemon is running before anything else: open Docker Desktop and confirm it shows "Engine running."

What success looks like: Every line in the health check table shows OK or a non-blocking warning. You can proceed to test a simple pull with docker pull mcr.microsoft.com/hello-world to confirm Docker itself is functional.

Azure Container Registry uses Microsoft Entra ID (formerly Azure Active Directory) as its primary authentication layer. When something in that chain breaks, expired tokens, wrong tenant, or a conditional access policy blocking the request, you get 401 Unauthorized or UNAUTHORIZED: authentication required.

First, make sure you're logged into the right tenant:

# See which account and tenant you're currently using
az account show

# If you need to switch tenants, log out and back in with the tenant ID
az logout
az login --tenant YOUR_TENANT_ID

If your organization has conditional access policies that restrict access to Azure resources from unmanaged devices or specific IP ranges, your login may succeed at the CLI level but fail at the registry level. You'll see this as a 401 that immediately follows a "Login Succeeded" message, confusing but explainable. In that case, your IT admin needs to check the conditional access policies in the Microsoft Entra admin center under Protection > Conditional Access > Policies.

For environments that use Managed Identity, common in AKS clusters and Azure VMs, don't use az acr login at all. Instead, authenticate via the managed identity directly:

# Authenticate using system-assigned managed identity
az login --identity

# Then log into the registry
az acr login --name YOUR_REGISTRY_NAME

If you're using a service principal (common in CI/CD pipelines), the login syntax is different:

docker login YOUR_REGISTRY_NAME.azurecr.io \
  --username YOUR_SERVICE_PRINCIPAL_APP_ID \
  --password YOUR_SERVICE_PRINCIPAL_PASSWORD

One mistake I see constantly: people pass the service principal's display name as the username instead of the Application (client) ID. The client ID is the GUID, find it in the Azure portal under Microsoft Entra ID > App registrations > [your app] > Overview. Use that GUID, not the name.

What success looks like: docker login or az acr login returns Login Succeeded with no error codes. You can then attempt a push or pull and it completes without a 401.

This is the most common misconfiguration I see in enterprise Azure setups. You can be a subscription Owner and still fail to push images if you haven't been explicitly assigned a registry-level role. Azure Container Registry uses Azure role-based access control (RBAC) for fine-grained permissions, and the standard subscription roles (Owner, Contributor, Reader) don't automatically grant the container-specific operations.

The three most important ACR-specific roles are:

• AcrPull, pull images from the registry
• AcrPush, push and pull images
• AcrDelete, delete images and tags

Check what roles your current identity has on the registry:

az role assignment list \
  --assignee YOUR_USER_OR_SP_OBJECT_ID \
  --scope $(az acr show --name YOUR_REGISTRY_NAME --query id --output tsv)

If the output is empty or doesn't include AcrPush/AcrPull, assign the right role:

# Assign AcrPush to a user
az role assignment create \
  --assignee USER_EMAIL_OR_OBJECT_ID \
  --role AcrPush \
  --scope $(az acr show --name YOUR_REGISTRY_NAME --query id --output tsv)

# Assign AcrPull to a service principal
az role assignment create \
  --assignee SERVICE_PRINCIPAL_APP_ID \
  --role AcrPull \
  --scope $(az acr show --name YOUR_REGISTRY_NAME --query id --output tsv)

Role assignments can take 2–5 minutes to propagate across Azure's authorization system. Don't test immediately, wait a few minutes, then run az acr login --name YOUR_REGISTRY_NAME again and retry your push or pull.

You can also assign roles through the Azure portal: navigate to your registry resource > Access control (IAM) > Add role assignment. Select the role, then search for your user, group, or service principal in the Members tab.

What success looks like: The az role assignment list command shows AcrPush or AcrPull in the output. After waiting a few minutes, your image push completes without an access denied error.

Even with perfect authentication and RBAC, you'll hit denied: requested access to the resource is denied or repository does not exist or may require 'docker login' if your image isn't tagged for your specific registry. This trips up people who are used to pushing to Docker Hub.

For Azure Container Registry, every image tag must include the full registry login server as the prefix. The format is:

YOUR_REGISTRY_NAME.azurecr.io/REPOSITORY_NAME:TAG

Here's the full workflow for pushing an image:

# Get your registry's login server (in case you're unsure)
az acr show --name YOUR_REGISTRY_NAME --query loginServer --output tsv

# Tag your local image for the registry
docker tag local-image-name:latest YOUR_REGISTRY_NAME.azurecr.io/myapp:v1.0

# Log in (if you haven't already)
az acr login --name YOUR_REGISTRY_NAME

# Push the tagged image
docker push YOUR_REGISTRY_NAME.azurecr.io/myapp:v1.0

And for pulling:

docker pull YOUR_REGISTRY_NAME.azurecr.io/myapp:v1.0

A common mistake: people tag with just the repository name (e.g., myapp:v1.0) and then try to push, Docker tries to push to Docker Hub instead of your ACR instance. Always include the full login server prefix.

To verify that your image actually made it into the registry, list the repositories:

az acr repository list --name YOUR_REGISTRY_NAME --output table

And to see the specific tags for a repository:

az acr repository show-tags --name YOUR_REGISTRY_NAME --repository myapp --output table

If you need to import an image from Docker Hub or another public registry into your ACR without pulling it locally first, very useful for air-gapped or bandwidth-constrained environments, the import command handles this entirely server-side:

az acr import \
  --name YOUR_REGISTRY_NAME \
  --source docker.io/library/nginx:latest \
  --image nginx:latest

What success looks like: az acr repository list shows your repository in the list. The tag appears when you run show-tags. Your deployment pipeline can now pull the image by its full ACR tag.

If you're setting up Azure Container Registry for the first time and hitting errors before you even get to pushing images, the problem is almost always in the creation step. Registry names must be globally unique across all of Azure, must be 5–50 characters long, and can only contain alphanumeric characters, no hyphens, no underscores. That last part surprises a lot of people.

Here's the correct creation workflow via Azure CLI:

# Create a resource group first (skip if you have one)
az group create --name myResourceGroup --location eastus

# Create the registry, choose your SKU carefully (Basic, Standard, or Premium)
az acr create \
  --resource-group myResourceGroup \
  --name mycompanyregistry \
  --sku Standard

On SKU selection: Basic is fine for personal development and testing. It's not for production. Standard gives you more storage and higher throughput, and it's the right default for small to mid-size teams. Premium unlocks geo-replication, private endpoints, content trust for image signing, and significantly higher storage limits, you need Premium for any multi-region deployment or enterprise compliance scenario.

After creation, verify the registry is up and get its login server:

az acr show --name mycompanyregistry --query loginServer --output tsv

This outputs something like mycompanyregistry.azurecr.io, that's the address you'll use in all your docker tag and docker push commands going forward.

To create the registry through the Azure portal instead: go to portal.azure.com > search for "Container registries" in the top search bar > click Create. Fill in your subscription, resource group, registry name, location, and SKU. Under the Networking tab, decide whether you need public access or private endpoint access (Premium only). Then hit Review + create and wait about 30 seconds for provisioning.

If you get The registry name is already taken, the name is globally reserved, try a longer, more unique name. If you get The subscription does not have enough quota to create this resource, you've hit your subscription's registry count limit, open a support request to increase it.

What success looks like: The az acr show command returns your registry's details including the login server URL. The registry appears in the Azure portal under Container registries in your resource group.