| name | aks-known-issues |
| license | MIT |
| metadata | {"author":"Microsoft","version":"0.1.0"} |
| description | Match exact AKS operation-failure signatures to documented causes and fixes. WHEN: an AKS create, scale, upgrade, node-image, or image-pull failure names VMCannotFitEphemeralOSDisk, LinkedAuthorizationFailed, NodePoolMcVersionIncompatible, 'NodeImageVersion is not accepted', SkuNotAvailable, ZonalAllocationFailed, OverconstrainedAllocationRequest, or an AKS vmssCSE/CSE nested signature: VMExtensionError_OutboundConnFail (exit 50), VMExtensionError_K8SAPIServerConnFail (exit 51), or VMExtensionError_K8SAPIServerDNSLookupFail (exit 52); also questions asking what a named AKS error means, and AllocationFailed only when its nested Azure message states internal error or insufficient capacity. DO NOT USE FOR: bare VMExtensionProvisioningError or AllocationFailed wrappers; numeric exit codes without AKS vmssCSE/CSE context; generic pod, node, DNS, ingress, timeout, SKU, capacity, or upgrade incidents without a cataloged signature (use aks-troubleshooting); non-AKS failures, which must not route to an AKS skill. |
AKS Known Issues
Turn 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.
Operating rules
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."
How to use
- Capture the exact failure — the error code, the full message, and the operation (
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).
- Match it against the table below (common set) or references/error-code-map.md (full catalog).
- Confirm the signature matches — same code, same operation class.
- Present the cause + the documented fix + the reference URL. Flag whether the fix is read-only (a config check) or a change that needs approval.
- Route out if there is no exact match: generic AKS incidents →
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.
Common known issues
| 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 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.
Boundary
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.
