aks-known-issues · diff
v0.1.0 to v0.1.0
1 added, 1 removed. Audit A to A.
---
name: aks-known-issues
license: MIT
metadata:
author: Microsoft
version: "0.1.0"
openclaw:
emoji: "🔖"
requires:
anyBins:
- az
- kubectl
- description: "Match an AKS operation failure against a curated, versioned table of documented known issues and error codes — each entry carrying the cause and the Microsoft-documented fix, workaround, or platform limitation. Deterministic error-string → diagnosis lookup for specific, named failures: AKS VM-extension / CSE provisioning errors with a documented nested signature (VMExtensionError_OutboundConnFail / exit 50, VMExtensionError_K8SAPIServerConnFail / exit 51, VMExtensionError_K8SAPIServerDNSLookupFail / exit 52, OrasPullUnauthorizedVMExtensionError / exit 212), SKU and allocation errors (SkuNotAvailable, ZonalAllocationFailed, OverconstrainedAllocationRequest, AllocationFailed with its full message), VMCannotFitEphemeralOSDisk, LinkedAuthorizationFailed, NodePoolMcVersionIncompatible, node-image / snapshot 'NodeImageVersion is not accepted', and network-isolated-cluster ACR pull failures. WHEN: an AKS create / scale / upgrade / image-pull fails with a NAMED error code or message; 'what does <error> mean on AKS?'; 'is <error> a known issue?'; an AKS vmssCSE / VM-extension exit code; an AKS SKU or allocation error. DO NOT USE FOR: a bare VMExtensionProvisioningError wrapper; a bare AllocationFailed code without its full nested Azure message (use aks-troubleshooting for investigation); an unclassified SKU / capacity allocation incident (use aks-troubleshooting); a numeric exit code without AKS CSE context; a natural-language 'allocation failed' symptom without the Azure error; non-AKS resources; or open-ended incidents with no specific error code — pod crashes, NotReady, DNS, ingress, or timeouts (use aks-troubleshooting for AKS incidents). Read-only: it explains and cites the documented fix, and never applies changes without explicit approval."
+ description: "Match an AKS operation failure against a curated, versioned table of documented known issues and error codes — each entry carrying the cause and the Microsoft-documented fix, workaround, or platform limitation. Deterministic error-string → diagnosis lookup for specific, named failures: AKS VM-extension / CSE provisioning errors with a documented nested signature (VMExtensionError_OutboundConnFail / exit 50, VMExtensionError_K8SAPIServerConnFail / exit 51, VMExtensionError_K8SAPIServerDNSLookupFail / exit 52, OrasPullUnauthorizedVMExtensionError / exit 212), SKU and allocation errors (SkuNotAvailable, ZonalAllocationFailed, OverconstrainedAllocationRequest, message-qualified AllocationFailed), VMCannotFitEphemeralOSDisk, LinkedAuthorizationFailed, NodePoolMcVersionIncompatible, node-image / snapshot 'NodeImageVersion is not accepted', and network-isolated-cluster ACR pull failures. ALLOCATION ROUTING: the full messages 'AllocationFailed: The VM allocation failed due to an internal error. Please retry later or try deploying to a different location' and 'AllocationFailed: We do not have sufficient capacity for the requested VM size' are cataloged signatures owned by this skill; they are not bare errors. A prompt that reports only the AllocationFailed code and explicitly has no nested Azure message is not a catalog match — route that bare-code investigation to aks-troubleshooting. WHEN: an AKS create / scale / upgrade / image-pull fails with one of the cataloged signatures; 'what does <error> mean on AKS?'; 'is <error> a known issue?'; an AKS vmssCSE / VM-extension exit code; or a message-qualified AKS SKU / allocation error. DO NOT USE FOR: a bare VMExtensionProvisioningError wrapper; an unclassified SKU / capacity allocation incident; a numeric exit code without AKS CSE context; a natural-language 'allocation failed' symptom without the Azure error; non-AKS resources; or open-ended incidents with no cataloged signature — pod crashes, NotReady, DNS, ingress, or timeouts (use aks-troubleshooting for AKS incidents). Read-only: it explains and cites the documented fix, and never applies changes without explicit approval."
---
# 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
1. **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).
2. **Match** it against the table below (common set) or [references/error-code-map.md](references/error-code-map.md) (full catalog).
3. **Confirm the signature** matches — same code, same operation class.
4. **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.
5. **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](https://learn.microsoft.com/troubleshoot/azure/azure-kubernetes/availability-performance/cluster-node-virtual-machine-failed-state#scenario-3-node-pool-is-in-a-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](https://learn.microsoft.com/troubleshoot/azure/azure-kubernetes/error-codes/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](https://learn.microsoft.com/troubleshoot/azure/azure-kubernetes/error-codes/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](https://learn.microsoft.com/troubleshoot/azure/azure-kubernetes/error-codes/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](https://learn.microsoft.com/azure/aks/concepts-storage#ephemeral-os-disks-in-aks) |
| 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](https://learn.microsoft.com/azure/azure-resource-manager/troubleshooting/error-sku-not-available) |
| 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](https://learn.microsoft.com/troubleshoot/azure/azure-kubernetes/error-codes/zonalallocation-allocationfailed-error) |
| 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](https://learn.microsoft.com/troubleshoot/azure/azure-kubernetes/error-codes/zonalallocation-allocationfailed-error) |
| 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](https://learn.microsoft.com/troubleshoot/azure/azure-kubernetes/error-codes/zonalallocation-allocationfailed-error) |
| `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](https://learn.microsoft.com/troubleshoot/azure/azure-kubernetes/error-codes/linkedauthorizationfailed-error) |
| `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](https://learn.microsoft.com/troubleshoot/azure/azure-kubernetes/error-codes/vmextensionerror-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](https://learn.microsoft.com/troubleshoot/azure/azure-kubernetes/error-codes/nodepoolmcversionincompatible-error) |
| `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](https://learn.microsoft.com/azure/aks/node-pool-snapshot#upgrading-a-node-pool-to-a-snapshot) |
The full catalog — with every error string, the mechanism, and the exact reference — is in [references/error-code-map.md](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.