Azure

How to troubleshoot Azure Container Registry authentication errors

Understanding ACR Authentication

Azure Container Registry (ACR) authentication errors prevent you from pushing, pulling, or managing container images. Common causes include disabled admin accounts, misconfigured managed identities, expired tokens, network restrictions, and SKU limitations. This guide covers every authentication scenario.

Why This Problem Matters in Production

In enterprise Azure environments, Azure Container Registry authentication issues rarely occur in isolation. They typically surface during peak usage periods, complex deployment scenarios, or when multiple services interact under load. Understanding the underlying architecture helps you move beyond symptom-level fixes to root cause resolution.

Before diving into the diagnostic commands below, it is important to understand the service’s operational model. Azure distributes workloads across multiple fault domains and update domains. When problems arise, they often stem from configuration drift between what was deployed and what the service runtime expects. This mismatch can result from ARM template changes that were not propagated, manual portal modifications that bypassed your infrastructure-as-code pipeline, or service-side updates that changed default behaviors.

Production incidents involving Azure Container Registry authentication typically follow a pattern: an initial trigger event causes a cascading failure that affects dependent services. The key to efficient troubleshooting is isolating the blast radius early. Start by confirming whether the issue is isolated to a single resource instance, affects an entire resource group, or spans the subscription. This scoping exercise determines whether you are dealing with a configuration error, a regional service degradation, or a platform-level incident.

The troubleshooting approach in this guide follows the industry-standard OODA loop: Observe the symptoms through metrics and logs, Orient by correlating findings with known failure patterns, Decide on the most likely root cause and remediation path, and Act by applying targeted fixes. This structured methodology prevents the common anti-pattern of random configuration changes that can make the situation worse.

Service Architecture Background

To troubleshoot Azure Container Registry authentication effectively, you need a mental model of how the service operates internally. Azure services are built on a multi-tenant platform where your resources share physical infrastructure with other customers. Resource isolation is enforced through virtualization, network segmentation, and quota management. When you experience performance degradation or connectivity issues, understanding which layer is affected helps you target your diagnostics.

The control plane handles resource management operations such as creating, updating, and deleting resources. The data plane handles the runtime operations that your application performs, such as reading data, processing messages, or serving requests. Control plane and data plane often have separate endpoints, separate authentication requirements, and separate rate limits. A common troubleshooting mistake is diagnosing a data plane issue using control plane metrics, or vice versa.

Azure Resource Manager (ARM) orchestrates all control plane operations. When you create or modify a resource, the request flows through ARM to the resource provider, which then provisions or configures the underlying infrastructure. Each step in this chain has its own timeout, retry policy, and error reporting mechanism. Understanding this chain helps you interpret error messages and identify which component is failing.

Diagnostic Command

# Run the built-in health check — catches most issues
az acr check-health \
  --name "myacr" \
  --yes

# Expected output for a healthy registry:
# Docker daemon status: available
# Docker client: available
# Docker client configuration: none detected
# DNS lookup to myacr.azurecr.io: OK
# Challenge: OK
# Fetch token: OK
# Login to myacr.azurecr.io: OK

The az acr check-health command validates Docker daemon availability, DNS resolution, token fetch, and login capability. Start here for any authentication issue.

Authentication Methods

Azure CLI Login (Interactive)

# Login to ACR using Azure AD token
az acr login --name "myacr"

# This creates a short-lived token (valid ~3 hours)
# For Docker commands, this token is stored in ~/.docker/config.json

Admin Account

# Check if admin is enabled
az acr show --name "myacr" --query "adminUserEnabled"

# Enable admin account (not recommended for production)
az acr update --name "myacr" --admin-enabled true

# Get admin credentials
az acr credential show --name "myacr" -o table

# Login with admin credentials
docker login myacr.azurecr.io \
  --username "myacr" \
  --password "password-from-above"

Admin accounts provide full push/pull access with no audit trail. Use managed identities or Azure AD service principals for production workloads.

Service Principal

# Create service principal with AcrPull role
az ad sp create-for-rbac \
  --name "acr-pull-sp" \
  --role AcrPull \
  --scopes "/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.ContainerRegistry/registries/myacr"

# Login with service principal
docker login myacr.azurecr.io \
  --username "{app-id}" \
  --password "{client-secret}"

Managed Identity

# Assign AcrPull role to a VM's system-assigned managed identity
az role assignment create \
  --assignee-object-id "$(az vm show --name myvm --resource-group myrg --query identity.principalId -o tsv)" \
  --role AcrPull \
  --scope "/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.ContainerRegistry/registries/myacr"

# Login from the VM using managed identity
az acr login --name "myacr" --identity

# For AKS — attach ACR to cluster
az aks update \
  --name "my-aks" \
  --resource-group "my-rg" \
  --attach-acr "myacr"

Repository-Scoped Tokens

# Create a scope map (read-only access to specific repository)
az acr scope-map create \
  --name "myapp-read" \
  --registry "myacr" \
  --repository "myapp" content/read

# Create a token using the scope map
az acr token create \
  --name "myapp-token" \
  --registry "myacr" \
  --scope-map "myapp-read"

# Generate password for the token
az acr token credential generate \
  --name "myapp-token" \
  --registry "myacr" \
  --password1

Common Error Messages

401 Unauthorized

Error response from daemon: Get https://myacr.azurecr.io/v2/: unauthorized: 
  authentication required

Causes:

  • Token expired — run az acr login --name myacr again
  • Wrong credentials — verify with az acr credential show
  • Service principal secret expired — regenerate with az ad sp credential reset
  • Missing RBAC role — assign AcrPull or AcrPush

403 Forbidden

Error response from daemon: denied: requesting token: 
  You don't have permission to access this resource

Causes:

  • Insufficient RBAC role — need AcrPush for push operations, AcrPull for pull
  • Network restrictions — IP not in allowed list or private endpoint required
  • Repository-scoped token lacks permission for the requested repository

CONNECTIVITY_DNS_ERROR

DNS lookup to myacr.azurecr.io failed. This could indicate a DNS configuration issue.

For private endpoint-enabled registries, ensure DNS resolution points to the private IP. Check with:

# Verify DNS resolution
nslookup myacr.azurecr.io
nslookup myacr.privatelink.azurecr.io

# Expected: should resolve to private IP (10.x.x.x) not public IP

Network-Related Issues

# Check network rules
az acr network-rule list --name "myacr" -o table

# Add IP to allowed list
az acr network-rule add \
  --name "myacr" \
  --ip-address "203.0.113.0/24"

# Check if public access is disabled
az acr show --name "myacr" --query "publicNetworkAccess"

# Temporarily enable public access for debugging
az acr update --name "myacr" --public-network-enabled true

Correlation and Cross-Service Diagnostics

Modern Azure architectures involve multiple services working together. A problem in Azure Container Registry authentication may actually originate in a dependent service. For example, a database timeout might be caused by a network security group rule change, a DNS resolution failure, or a Key Vault access policy that prevents secret retrieval for the connection string.

Use Azure Resource Graph to query the current state of all related resources in a single query. This gives you a snapshot of the configuration across your entire environment without navigating between multiple portal blades. Combine this with Activity Log queries to build a timeline of changes that correlates with your incident window.

Application Insights and Azure Monitor provide distributed tracing capabilities that follow a request across service boundaries. When a user request touches multiple Azure services, each service adds its span to the trace. By examining the full trace, you can see exactly where latency spikes or errors occur. This visibility is essential for troubleshooting in microservices architectures where a single user action triggers operations across dozens of services.

For complex incidents, consider creating a war room dashboard in Azure Monitor Workbooks. This dashboard should display the key metrics for all services involved in the affected workflow, organized in the order that a request flows through them. Having this visual representation during an incident allows the team to quickly identify which service is the bottleneck or failure point.

SKU Limitations

Feature Basic Standard Premium
Storage 10 GiB 100 GiB 500 GiB
Webhooks 2 10 500
Geo-replication No No Yes
Private Link No No Yes
Customer-managed keys No No Yes
Content Trust No No Yes
Scope Maps/Tokens No No Yes 
# Upgrade SKU
az acr update --name "myacr" --sku Premium

AKS Integration

# Verify AKS-ACR integration
az aks check-acr \
  --name "my-aks" \
  --resource-group "my-rg" \
  --acr "myacr.azurecr.io"

# If pull fails from AKS, check the kubelet identity
az aks show \
  --name "my-aks" \
  --resource-group "my-rg" \
  --query "identityProfile.kubeletidentity.objectId" -o tsv

# Verify role assignment exists
az role assignment list \
  --assignee "{kubelet-identity-object-id}" \
  --scope "/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.ContainerRegistry/registries/myacr" \
  -o table

Kubernetes Image Pull Secret (Non-AKS)

# Create image pull secret
kubectl create secret docker-registry acr-secret \
  --docker-server="myacr.azurecr.io" \
  --docker-username="{service-principal-id}" \
  --docker-password="{service-principal-secret}" \
  --docker-email="admin@example.com"

# Reference in pod spec
# spec:
#   imagePullSecrets:
#     - name: acr-secret
#   containers:
#     - name: myapp
#       image: myacr.azurecr.io/myapp:v1

Troubleshooting Checklist

  1. Run az acr check-health --name myacr --yes
  2. Verify authentication method (CLI, admin, SP, managed identity)
  3. Check RBAC role assignments (AcrPull, AcrPush, AcrDelete)
  4. Verify network access (firewall rules, private endpoints, public access)
  5. Check token expiration (CLI tokens last ~3 hours, SP secrets have expiry dates)
  6. Verify SKU supports required features (private link requires Premium)
  7. For AKS, run az aks check-acr
  8. Check Docker daemon is running locally

Monitoring and Alerting Strategy

Reactive troubleshooting is expensive. For every hour spent diagnosing a production issue, organizations lose revenue, customer trust, and engineering productivity. A proactive monitoring strategy for Azure Container Registry authentication should include three layers of observability.

The first layer is metric-based alerting. Configure Azure Monitor alerts on the key performance indicators specific to this service. Set warning thresholds at 70 percent of your limits and critical thresholds at 90 percent. Use dynamic thresholds when baseline patterns are predictable, and static thresholds when you need hard ceilings. Dynamic thresholds use machine learning to adapt to your workload’s natural patterns, reducing false positives from expected daily or weekly traffic variations.

The second layer is log-based diagnostics. Enable diagnostic settings to route resource logs to a Log Analytics workspace. Write KQL queries that surface anomalies in error rates, latency percentiles, and connection patterns. Schedule these queries as alert rules so they fire before customers report problems. Consider implementing a log retention strategy that balances diagnostic capability with storage costs, keeping hot data for 30 days and archiving to cold storage for compliance.

The third layer is distributed tracing. When Azure Container Registry authentication participates in a multi-service transaction chain, distributed tracing via Application Insights or OpenTelemetry provides end-to-end visibility. Correlate trace IDs across services to pinpoint exactly where latency or errors originate. Without this correlation, troubleshooting multi-service failures becomes a manual, time-consuming process of comparing timestamps across different log streams.

Beyond alerting, implement synthetic monitoring that continuously tests critical user journeys even when no real users are active. Azure Application Insights availability tests can probe your endpoints from multiple global locations, detecting outages before your users do. For Azure Container Registry authentication, create synthetic tests that exercise the most business-critical operations and set alerts with a response time threshold appropriate for your SLA.

Operational Runbook Recommendations

Document the troubleshooting steps from this guide into your team’s operational runbook. Include the specific diagnostic commands, expected output patterns for healthy versus degraded states, and escalation criteria for each severity level. When an on-call engineer receives a page at 2 AM, they should be able to follow a structured decision tree rather than improvising under pressure.

Consider automating the initial diagnostic steps using Azure Automation runbooks or Logic Apps. When an alert fires, an automated workflow can gather the relevant metrics, logs, and configuration state, package them into a structured incident report, and post it to your incident management channel. This reduces mean time to diagnosis (MTTD) by eliminating the manual data-gathering phase that often consumes the first 15 to 30 minutes of an incident response.

Implement a post-incident review process that captures lessons learned and feeds them back into your monitoring and runbook systems. Each incident should result in at least one improvement to your alerting rules, runbook procedures, or service configuration. Over time, this continuous improvement cycle transforms your operations from reactive fire-fighting to proactive incident prevention.

Finally, schedule regular game day exercises where the team practices responding to simulated incidents. Azure Chaos Studio can inject controlled faults into your environment to test your monitoring, alerting, and runbook effectiveness under realistic conditions. These exercises build muscle memory and identify gaps in your incident response process before real incidents expose them.

Summary

ACR authentication errors trace back to expired tokens (az acr login to refresh), missing RBAC roles (assign AcrPull/AcrPush), network restrictions (check firewall and private endpoint DNS), and SKU limitations (private link requires Premium). Start diagnostics with az acr check-health. For AKS integration, use az aks update --attach-acr and verify with az aks check-acr. Prefer managed identities over admin accounts for production.

For more details, refer to the official documentation: Introduction to Azure Container Registry, Troubleshoot registry login.

Leave a Reply