Aks Known Issues

From the author

Lookup documented AKS fixes only when the prompt includes an exact catalog signature and all of its qualifiers: VMCannotFitEphemeralOSDisk; NodePoolMcVersionIncompatible; 'NodeImageVersion is not accepted'; AKS SkuNotAvailable with size, location, and zone; ZonalAllocationFailed with insufficient zone capacity; OverconstrainedAllocationRequest with listed constraints; nested AKS vmssCSE/CSE VMExtensionError_OutboundConnFail, VMExtensionError_K8SAPIServerConnFail, or VMExtensionError_K8SAPIServerDNSLookupFail; or AllocationFailed with the full cataloged internal-error or insufficient-regional-capacity message. Never use for quota errors, code-only or bare wrappers, generic symptoms, incomplete signatures, or failures outside AKS; use aks-troubleshooting or azure-diagnostics.

— the description by Microsoft

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured lookup for known Azure Kubernetes Service (AKS) issues. It is designed to be used only when a user provides an exact, cataloged error signature and the required operational context. By matching specific error codes against a curated catalog, the skill delivers the root cause, a Microsoft Learn citation, and a proposed remediation path. It emphasizes safety by requiring read-only verification before any proposed fix and mandates explicit user approval for any potential system mutation.

What it does

Matches exact AKS error signatures against a documented catalog.
Provides the root cause and official Microsoft Learn documentation for identified issues.
Performs read-only verification of the error state.
Proposes specific remediation steps for the identified issue.
Requires explicit user approval before any system mutation is performed.

When to use it

When you have an exact, full error signature from an AKS operation.
When you need to identify the cause of specific provisioning or allocation failures.
When you require a documented, official fix for a known AKS error code.
When you have confirmed the error is specific to AKS and not a generic or quota-related issue.

Advantages

Reduces ambiguity by requiring exact error signatures and qualifiers.
Ensures safety by mandating read-only verification and explicit user approval.
Provides direct links to official Microsoft troubleshooting documentation.
Prevents misdiagnosis by explicitly excluding generic or quota-related errors.

Usage examples

“My AKS node pool failed with VMCannotFitEphemeralOSDisk.”: The agent identifies the ephemeral OS disk size mismatch, provides the relevant Microsoft Learn link, verifies the current configuration, and proposes a fix involving a different SKU or disk type.
“I am seeing VMExtensionError_OutboundConnFail during node provisioning.”: The agent confirms the CSE outbound connection failure, suggests checking firewall/proxy/NSG rules, and provides the link to the official troubleshooting guide.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/microsoft/aks-known-issues/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip aks-known-issues.zip -d .agents/skills

Documentation by Microsoft

Quick Reference

Property	Value
Best for	Exact signature plus AKS operation
Output	Cause, fix, and Learn citation

Use the catalog.

When to Use This Skill

Named catalog signatures only. Generic AKS → aks-troubleshooting; non-AKS → no AKS skill.

If every qualifier for a catalog row is not present, do not use this skill. This catalog has no quota-error rows; route AKS quota incidents to aks-troubleshooting.

MCP Tools

None required. Use advertised read-only Azure tools or CLI queries.

Workflow

Capture exact code, nested message, operation, and AKS resource.
Require every qualifier; codes are not substrings.
Give cause, fix, citation, and read-only verification.
State what ran; require explicit approval before every mutation.

Error Handling

Input	Response
Bare wrapper/number	Request nested signature and CSE context
Generic AKS	`aks-troubleshooting`
Non-AKS	No AKS skill

Files

ATTRIBUTION.mdAdded by AutoGineer974 B
LICENSELicence file added by AutoGineer1.1 KiB
SKILL.md1.9 KiB
references/error-code-map.md6.8 KiB

references/error-code-map.md

AKS known-issue catalog

Match the exact signature and AKS operation context. Every answer must include, in order: the match and cause; citation; Read-only verification (not run); and Proposed fix (requires explicit user approval). Never present a mutation without that gate.

VM extension and CSE provisioning

The outer VMExtensionProvisioningError or a number alone is insufficient; a numeric exit requires AKS vmssCSE/CSE context.

Signature	Cause	Verify, then documented fix	Microsoft Learn
`VMExtensionError_OutboundConnFail`, `ERR_OUTBOUND_CONN_FAIL`, or exit 50	CSE cannot reach endpoints needed for node packages	Test `mcr.microsoft.com:443`; inspect firewall, proxy, NSG, UDR, and AKS egress rules; correct the blocking path	OutboundConnFail
`VMExtensionError_K8SAPIServerConnFail`, `ERR_K8S_API_SERVER_CONN_FAIL`, or exit 51	Node cannot reach the API server on TCP 443	Test the API FQDN on 443; inspect NSG, UDR, firewall/proxy, authorized IPs, private endpoint, and TLS inspection; correct the failing path	APIServerConnFail
`VMExtensionError_K8SAPIServerDNSLookupFail`, `ERR_K8S_API_SERVER_DNS_LOOKUP_FAIL`, or exit 52	Node cannot resolve the API-server FQDN	Resolve the FQDN and inspect DNS port 53, forwarders, and private-zone records/links; correct DNS	APIServerDNSLookupFail

Node-pool provisioning and allocation

Signature	Cause	Verify, then documented fix	Microsoft Learn
`VMCannotFitEphemeralOSDisk`	Requested ephemeral OS disk exceeds the SKU cache/temp capacity	Compare disk size with SKU storage; choose a fitting SKU, smaller disk, or managed disk. Type and size require a new pool	Ephemeral OS disks
AKS node-pool `SkuNotAvailable` naming size, location, and zone	SKU is unavailable for that subscription and placement; Spot capacity can also cause it	Inspect `az vm list-skus`; choose another size, zone, or region, or request SKU access. Do not call it quota exhaustion	SkuNotAvailable
AKS `ZonalAllocationFailed` stating insufficient capacity in a zone	Requested placement lacks capacity; a proximity placement group can constrain it	Check PPG association; use another SKU, zone, region, or pool. For upgrades, consider `maxUnavailable` with `maxSurge=0`	AKS allocation errors
AKS `OverconstrainedAllocationRequest` listing constraints	The named SKU, networking, zone, disk, or PPG combination cannot allocate	Read the listed constraints; relax only a named constraint or choose another placement	AKS allocation errors
AKS `AllocationFailed`: `The VM allocation failed due to an internal error`	Internal allocation error	Confirm the failed operation and full message read-only; only after approval, retry later or deploy elsewhere. Do not recast it as quota or capacity	AKS AllocationFailed
AKS/backing VMSS `AllocationFailed` stating insufficient regional capacity	Requested regional placement lacks VM capacity	Confirm the full message; retry later or use another SKU, zone, region, or pool	VMSS allocation failures

Images and upgrades

Signature	Cause	Verify, then documented fix	Microsoft Learn
`NodeImageVersion ... is not accepted` and says only current or `latest` is allowed	Snapshot/rollback-pinned pool requested another image	Compare current and requested images; run a node-image-only upgrade without `--snapshot-id` to use the latest supported image	Node-pool snapshots
`NodePoolMcVersionIncompatible`	Pool is over two minor versions behind, or newer than the control plane	Read both versions and available upgrades; only after approval, upgrade within two minors without exceeding the control plane	NodePoolMcVersionIncompatible
`K8sVersionNotSupported` during AKS upgrade	Target version is unsupported in the region	Read supported versions and choose one offered in that region	AKS upgrade blocked
`OperationNotAllowed` stating the requested upgrade is unavailable	Requested path skips a required minor version	Read available upgrades and upgrade through supported minor versions	AKS upgrade blocked

Identity and image pulls

Signature	Cause	Verify, then documented fix	Microsoft Learn
AKS create/deploy `LinkedAuthorizationFailed` naming a linked scope and action	Deployment identity lacks that action on the linked resource	Read the identity, action, scope, and assignments; grant the required role at the linked scope	LinkedAuthorizationFailed
Network-isolated AKS `OrasPullUnauthorizedVMExtensionError` / CSE exit 212	Kubelet identity lacks bootstrap ACR pull access or VM binding	Inspect logs, identity binding, and ACR roles; assign `AcrPull` or the ABAC repository-reader role as applicable	OrasPullUnauthorized
AKS pod image pull `401 Unauthorized` / `failed to authorize` from ACR	Kubelet identity, service principal, or pull secret lacks registry authorization	Inspect pod events and `az aks check-acr`; correct the applicable ACR role or credential	AKS image-pull errors

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Modal
K-Dense· Community
A serverless cloud platform for deploying and scaling Python applications, AI models, and GPU-accelerated workloads.
Cloud and DevOpsClaude CodeClaude appsOpenAI Codex+14 more
Apache-2.0Low riskGitHub stars of the source repository56.4k
Cloud Infrastructure Network Engineer
Seth Hobson· Community
An expert network engineer persona specializing in cloud architecture, security, and performance optimization.
Cloud and DevOpsClaude Code
MITGitHub stars of the source repository42.3k
Deployment Validation Cloud Architect
Seth Hobson· Community
Expert cloud architect for multi-cloud infrastructure, cost optimization, and resilient system design.
Cloud and DevOpsClaude Code
MITGitHub stars of the source repository42.3k
Airflow Dag Patterns
Seth Hobson· Community
Best practices and design patterns for building and maintaining production-ready Apache Airflow DAGs.
Cloud and DevOpsClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository42.3k
Cost Optimization
Seth Hobson· Community
A comprehensive framework for reducing cloud infrastructure costs across AWS, Azure, GCP, and OCI.
Cloud and DevOpsClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository42.3k
Hybrid Cloud Networking
Seth Hobson· Community
A guide to configuring secure, high-performance network connectivity between on-premises infrastructure and major cloud providers.
Cloud and DevOpsClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository42.3k

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download aks-known-issues.zip