AKS ImagePullBackOff from ACR: 401 Unauthorized
A 401 pulling from Azure Container Registry means the cluster identity lacks the right role, or a credential expired. Check the role and attach ACR.
What you see
failed to authorize: failed to fetch oauth token: unexpected status: 401 Unauthorizedno match for platform in manifestfollowed by a 401 for an architecture mismatch
What it means
An AKS pull from ACR has three stages: authentication and authorization, the registry's login endpoint, and the data endpoint that serves image layers. A 401 Unauthorized is the first stage: the node's identity has no valid right to pull.
AKS uses the kubelet's managed identity (or a service principal) to authenticate. The AKS to ACR integration assigns that identity the AcrPull role, or Container Registry Repository Reader for registries with attribute-based access control.
How to confirm the cause
- 1Read the failing event
kubectl describe pod POD_NAME -n NAMESPACE
Match the message to a cause below.
- 2Let Azure test the cluster-to-registry path
az aks check-acr --resource-group RESOURCE_GROUP --name CLUSTER_NAME --acr REGISTRY.azurecr.io
- 3List role assignments on the registry
az role assignment list --scope /subscriptions/SUBSCRIPTION_ID/resourceGroups/RESOURCE_GROUP/providers/Microsoft.ContainerRegistry/registries/REGISTRY -o table
Look for
AcrPull(orContainer Registry Repository Readeron ABAC-enabled registries) for the kubelet identity.
Causes and fixes
The role is missing
- HOW TO TELL
- No AcrPull assignment for the cluster's identity.
- ROOT CAUSE
- The integration was never set up, or the role assignment was removed.
- FIX
- Attach the registry, which assigns AcrPull to the kubelet identity. For ABAC-enabled registries
--attach-acrdoes not add the Repository Reader role, so assign it manually.az aks update -n CLUSTER_NAME -g RESOURCE_GROUP --attach-acr ACR_RESOURCE_ID
The service principal secret expired or changed
- HOW TO TELL
- A cluster that uses a service principal, and
az ad app credential listshows an end date in the past. - ROOT CAUSE
- The cluster authenticates with a secret, and secrets expire. The role assignment may also still reference an old service principal.
- FIX
- Check the expiry and update the cluster's credentials. Compare the cluster's service principal with the one on the role assignment.
The kubelet identity was removed from the node scale set
- HOW TO TELL
- Nodes cannot pull, and the identity is not listed on the scale set.
- ROOT CAUSE
- Someone edited the node resource group by hand. AKS does not support modifying the scale sets directly.
- FIX
- Reconcile so AKS puts the identity back, then consider locking the node resource group.
az aks update --resource-group RESOURCE_GROUP --name CLUSTER_NAME
Image architecture does not match the node
- HOW TO TELL
no match for platform in manifestandexec /canipull: exec format error.- ROOT CAUSE
- The image was built for ARM64 and the node is AMD64, or the other way round.
- FIX
- Push images that match the node architecture, or push multi-architecture images.
Credential cache not refreshed after a change
- HOW TO TELL
- A 401 although the role assignment looks right, soon after migrating or rotating identity.
- ROOT CAUSE
- The kubelet credential provider caches tokens and does not pick up a new identity binding at once.
- FIX
- Wait a few minutes, then reconcile the cluster. If it persists beyond about five minutes, upgrade the node image.
az aks update --resource-group RESOURCE_GROUP --name CLUSTER_NAME az aks nodepool upgrade --resource-group RESOURCE_GROUP --cluster-name CLUSTER_NAME --name NODEPOOL --node-image-only
How to stop it coming back
- Set up the ACR integration in your IaC, not by hand.
- Prefer managed identity over service principals, so there is no secret to expire.
- Lock the node resource group against manual edits.
Keep going
- Runbook: AKS pull from ACR fails: 403, i/o timeout, TLS handshake, blocked data endpoint
- Runbook: ImagePullBackOff: the pod can't pull its image
- Cheat sheet: Azure CLI
- Cheat sheet: kubectl
- Lesson: the kubernetes topic in Learn
Sources
Microsoft Learn (learn.microsoft.com), read 18 Nov 2026. The page's own metadata shows it was last updated 30 Oct 2026.