Terminal
Terminal/Skill
Matches exact AKS error codes and messages, such as VMExtensionError exit codes or ZonalAllocationFailed, to documented causes and fixes.
By Microsoft
Works with
npx skills add azure/aks-skills --skill aks-known-issuesTurn a specific AKS error code or message into a documented diagnosis: the cause, the Microsoft-documented fix or workaround, and the reference that proves it. This skill is a deterministic string→diagnosis matcher, not an open-ended investigation — it fires when the failure already names itself (an error code, an extension exit code, a rejected value) and you want the known answer fast.
Read-only by default. Do not upgrade, reimage, delete, reconcile, scale, or modify role assignments on the cluster or its Azure resources unless the user explicitly asks. Match the error, explain the cause, cite the documented fix — then apply it only on explicit approval.
Match on the signature, not the vibe. Only claim a known issue when the actual error string matches the entry (code, message, and the operation that produced it). Compare error codes as exact values, not substrings: ZonalAllocationFailed is not the AllocationFailed code. If the symptom is generic and no specific error code is present, this is not the right skill — route to aks-troubleshooting.
Cite the source. Every match names its Microsoft Learn reference so the user (or a support engineer) can verify the fix before acting. If you cannot cite a documented source, say so and hand off — do not invent a "known issue."
az aks nodepool show on a provisioningState=Failed pool surfaces the code; VM-extension failures surface vmssCSE exit codes; ARM/CLI returns the error verbatim).aks-troubleshooting; non-AKS failures → no AKS skill. A bare VMExtensionProvisioningError or AllocationFailed is not enough to diagnose. A numeric exit code also requires AKS vmssCSE / CSE context. Request the nested error, complete message, operation, and AKS resource context.| Error / signature | What it means | Documented fix | Microsoft Learn |
|---|---|---|---|
Node pool provisioningState=Failed | The backing VMSS hit an error during provision/scale/update — capacity, quota, network, policy, or a resource lock | Read the exact code from az aks nodepool show, then az vmss show; resolve the underlying cause (quota/capacity/policy/lock) and reconcile with az aks nodepool update | Node/VM failed state |
AKS vmssCSE / VMExtensionProvisioningError containing VMExtensionError_OutboundConnFail, OutboundConnFailVMExtensionError, ERR_OUTBOUND_CONN_FAIL, or exit 50 | The CSE couldn't establish the outbound connection needed to obtain node-provisioning packages | Test mcr.microsoft.com:443; inspect the firewall, proxy, NSG, UDR, and required AKS FQDN/port rules. For private clusters with custom DNS, verify Azure DNS 168.63.129.16 is an upstream resolver | VMExtensionError_OutboundConnFail |
AKS vmssCSE / VMExtensionProvisioningError containing VMExtensionError_K8SAPIServerConnFail, K8SAPIServerConnFailVMExtensionError, ERR_K8S_API_SERVER_CONN_FAIL, or exit 51 | The node couldn't connect to the AKS API-server endpoint on TCP 443 | Test <api-server-fqdn>:443; inspect NSG, UDR, firewall/proxy, authorized IP ranges, private-endpoint status, and TLS inspection | VMExtensionError_K8SAPIServerConnFail |
AKS vmssCSE / VMExtensionProvisioningError containing VMExtensionError_K8SAPIServerDNSLookupFail, K8SAPIServerDNSLookupFailVMExtensionError, ERR_K8S_API_SERVER_DNS_LOOKUP_FAIL, or exit 52 | The node couldn't resolve the cluster API-server FQDN | Resolve the cluster FQDN with nslookup or dig and verify DNS reachability on port 53 and forwarders. For private clusters, also verify the private-zone VNet link and A record | VMExtensionError_K8SAPIServerDNSLookupFail |
VMCannotFitEphemeralOSDisk | The requested OS disk doesn't fit the VM SKU's cache/temp storage, but ephemeral was requested (or defaulted) | Use a VM SKU with a large enough cache/temp, reduce --node-osdisk-size, or set --node-osdisk-type Managed. OS disk type/size can't change in place — create a new node pool and migrate | Ephemeral OS disks |
AKS node-pool SkuNotAvailable with the requested size, location, and zone in the message | The VM SKU is unavailable for this subscription in that placement; Spot capacity can also cause this code | Inspect restrictions with az vm list-skus --location <region> --size <partial-size> --all --output table; select another size, zone, or region, or request the required SKU. Do not label it quota exhaustion | SkuNotAvailable |
AKS ZonalAllocationFailed: Allocation failed. We do not have sufficient capacity for the requested VM size in this zone | Azure lacks capacity for the requested VM size in that availability zone; an associated proximity placement group can also constrain placement | Use another SKU, zone, region, or node pool. Check for a proximity placement group before attributing the constraint to one. During upgrades only, set maxUnavailable > 0 together with maxSurge=0 to avoid requesting surge capacity | AKS allocation errors |
AKS node-pool OverconstrainedAllocationRequest with the listed constraints | The requested combination of SKU, networking, zone, ephemeral disk, proximity placement group, or other listed constraints can't be allocated | Read the listed constraints, then relax the named constraint or use another SKU, zone, region, or node pool. Remove a proximity placement group only when it is actually listed or configured | AKS allocation errors |
AKS create / scale / upgrade AllocationFailed with its full nested message | The documented internal-error form requires a later retry or another location; a message that explicitly says insufficient capacity is a placement-capacity failure | Follow the nested message: retry later or use another location for the internal-error form; for an explicit capacity form, use another SKU, zone, region, or node pool. During upgrades only, set maxUnavailable > 0 together with maxSurge=0 to avoid requesting surge capacity | AKS allocation errors |
LinkedAuthorizationFailed | The cluster identity (managed identity or SP) lacks a role assignment on a linked resource named in the error (e.g. a subnet, DDoS plan, or route table) | Grant the identity the action shown in the error at the linked resource scope; verify role-assignment propagation and that the linked resource still exists | LinkedAuthorizationFailed |
OrasPullUnauthorizedVMExtensionError / vmssCSE exit 212 | On a network-isolated cluster (outbound none/block), the kubelet identity can't pull bootstrap images from the private ACR cache | Ensure the kubelet identity has AcrPull (or the ABAC repository-reader role) on the bootstrap ACR and is bound to the VM | OrasPullUnauthorized |
NodePoolMcVersionIncompatible | A node pool is (or would become) more than 3 minor versions behind the control plane | Upgrade the node pool to a version ≤ the control-plane version; don't skip minor versions | NodePoolMcVersionIncompatible |
NodeImageVersion ... is not accepted | A snapshot- or rollback-pinned node pool is being set to a node-image version that isn't its current version or latest | Use az aks nodepool upgrade --node-image-only (no --snapshot-id) to move to the latest supported image, respecting the OS SKU | Node pool snapshots |
The full catalog — with every error string, the mechanism, and the exact reference — is in references/error-code-map.md. Keep that file the single source of truth and add new entries there as documented issues are confirmed.
This skill owns named, documented AKS failures. The outer VMExtensionProvisioningError wrapper, a bare AllocationFailed, or an exit number outside AKS vmssCSE / CSE output doesn't identify one cause: require the documented nested signature and operation context before matching. Anything without a specific error signature — a pod crashing, a node going NotReady, DNS or ingress misbehaving, intermittent timeouts, or Kubernetes FailedScheduling — is a live investigation and belongs to aks-troubleshooting, which will route to a packet capture (aks-network-capture) or another skill as the evidence dictates. Errors for non-AKS VMs or VM scale sets do not route to an AKS skill.