AzureMid

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 Unauthorized
  • no match for platform in manifest followed 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

  1. 1
    Read the failing event
    kubectl describe pod POD_NAME -n NAMESPACE

    Match the message to a cause below.

  2. 2
    Let Azure test the cluster-to-registry path
    az aks check-acr --resource-group RESOURCE_GROUP --name CLUSTER_NAME --acr REGISTRY.azurecr.io
  3. 3
    List 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 (or Container Registry Repository Reader on 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-acr does 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 list shows 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 manifest and exec /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

Sources

Microsoft Learn (learn.microsoft.com), read 18 Nov 2026. The page's own metadata shows it was last updated 30 Oct 2026.

Search

Search cheat sheets and projects