references/error-code-map.md
AKS known-issue catalog
Match the exact signature and AKS operation context. Every answer must include, in order: the match and cause; citation; Read-only verification (not run); and Proposed fix (requires explicit user approval). Never present a mutation without that gate.
VM extension and CSE provisioning
The outer VMExtensionProvisioningError or a number alone is insufficient; a
numeric exit requires AKS vmssCSE/CSE context.
| Signature | Cause | Verify, then documented fix | Microsoft Learn |
|---|---|---|---|
| VMExtensionError_OutboundConnFail, ERR_OUTBOUND_CONN_FAIL, or exit 50 | CSE cannot reach endpoints needed for node packages | Test mcr.microsoft.com:443; inspect firewall, proxy, NSG, UDR, and AKS egress rules; correct the blocking path | OutboundConnFail |
| VMExtensionError_K8SAPIServerConnFail, ERR_K8S_API_SERVER_CONN_FAIL, or exit 51 | Node cannot reach the API server on TCP 443 | Test the API FQDN on 443; inspect NSG, UDR, firewall/proxy, authorized IPs, private endpoint, and TLS inspection; correct the failing path | APIServerConnFail |
| VMExtensionError_K8SAPIServerDNSLookupFail, ERR_K8S_API_SERVER_DNS_LOOKUP_FAIL, or exit 52 | Node cannot resolve the API-server FQDN | Resolve the FQDN and inspect DNS port 53, forwarders, and private-zone records/links; correct DNS | APIServerDNSLookupFail |
Node-pool provisioning and allocation
| Signature | Cause | Verify, then documented fix | Microsoft Learn |
|---|---|---|---|
| VMCannotFitEphemeralOSDisk | Requested ephemeral OS disk exceeds the SKU cache/temp capacity | Compare disk size with SKU storage; choose a fitting SKU, smaller disk, or managed disk. Type and size require a new pool | Ephemeral OS disks |
| AKS node-pool SkuNotAvailable naming size, location, and zone | SKU is unavailable for that subscription and placement; Spot capacity can also cause it | Inspect az vm list-skus; choose another size, zone, or region, or request SKU access. Do not call it quota exhaustion | SkuNotAvailable |
| AKS ZonalAllocationFailed stating insufficient capacity in a zone | Requested placement lacks capacity; a proximity placement group can constrain it | Check PPG association; use another SKU, zone, region, or pool. For upgrades, consider maxUnavailable with maxSurge=0 | AKS allocation errors |
| AKS OverconstrainedAllocationRequest listing constraints | The named SKU, networking, zone, disk, or PPG combination cannot allocate | Read the listed constraints; relax only a named constraint or choose another placement | AKS allocation errors |
| AKS AllocationFailed: The VM allocation failed due to an internal error | Internal allocation error | Confirm the failed operation and full message read-only; only after approval, retry later or deploy elsewhere. Do not recast it as quota or capacity | AKS AllocationFailed |
| AKS/backing VMSS AllocationFailed stating insufficient regional capacity | Requested regional placement lacks VM capacity | Confirm the full message; retry later or use another SKU, zone, region, or pool | VMSS allocation failures |
Images and upgrades
| Signature | Cause | Verify, then documented fix | Microsoft Learn |
|---|---|---|---|
| NodeImageVersion ... is not accepted and says only current or latest is allowed | Snapshot/rollback-pinned pool requested another image | Compare current and requested images; run a node-image-only upgrade without --snapshot-id to use the latest supported image | Node-pool snapshots |
| NodePoolMcVersionIncompatible | Pool is over two minor versions behind, or newer than the control plane | Read both versions and available upgrades; only after approval, upgrade within two minors without exceeding the control plane | NodePoolMcVersionIncompatible |
| K8sVersionNotSupported during AKS upgrade | Target version is unsupported in the region | Read supported versions and choose one offered in that region | AKS upgrade blocked |
| OperationNotAllowed stating the requested upgrade is unavailable | Requested path skips a required minor version | Read available upgrades and upgrade through supported minor versions | AKS upgrade blocked |
Identity and image pulls
| Signature | Cause | Verify, then documented fix | Microsoft Learn |
|---|---|---|---|
| AKS create/deploy LinkedAuthorizationFailed naming a linked scope and action | Deployment identity lacks that action on the linked resource | Read the identity, action, scope, and assignments; grant the required role at the linked scope | LinkedAuthorizationFailed |
| Network-isolated AKS OrasPullUnauthorizedVMExtensionError / CSE exit 212 | Kubelet identity lacks bootstrap ACR pull access or VM binding | Inspect logs, identity binding, and ACR roles; assign AcrPull or the ABAC repository-reader role as applicable | OrasPullUnauthorized |
| AKS pod image pull 401 Unauthorized / failed to authorize from ACR | Kubelet identity, service principal, or pull secret lacks registry authorization | Inspect pod events and az aks check-acr; correct the applicable ACR role or credential | AKS image-pull errors |