aks-known-issues v0.1.0A

Immutable. This exact content is served forever at /api/v1/blob/d6eeb475b7ee3bcc.

---
name: aks-known-issues
license: MIT
metadata:
  author: Microsoft
  version: "0.1.0"
  openclaw:
    emoji: "🔖"
    requires:
      anyBins:
        - az
        - kubectl
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

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.