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 (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

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.