|
| 1 | +--- |
| 2 | +title: Troubleshoot AKS upgrade errors because of version skew, incompatibility, or lack of support |
| 3 | +description: Learn how to troubleshoot AKS upgrade not allowed or blocked because of unsupported Kubernetes version or node pool version skew. |
| 4 | +ms.date: 08/22/2025 |
| 5 | +editor: v-jsitser |
| 6 | +ms.reviewer: v-liuamson |
| 7 | +ms.service: azure-kubernetes-service |
| 8 | +ms.custom: sap:Create, Upgrade, Scale and Delete operations (cluster or nodepool) |
| 9 | +#Customer intent: As an Azure Kubernetes user, I want to troubleshoot an AKS upgrade not allowed or blocked because of an unsupported Kubernetes version or node pool version skew so that I can successfully upgrade an AKS cluster by using the Azure CLI. |
| 10 | +--- |
| 11 | +# Troubleshoot AKS upgrade errors because of version skew, incompatibility, or lack of support |
| 12 | + |
| 13 | +## Prerequisites |
| 14 | + |
| 15 | +This article requires Azure CLI version 2.67.0 or a later version. To find the version number, run `az --version`. If you have to install or upgrade the Azure CLI, see [How to install the Azure CLI](/cli/azure/install-azure-cli). |
| 16 | + |
| 17 | +For more detailed information about the upgrade process, see the "Upgrade an AKS cluster" section in [Upgrade options and recommendations for Azure Kubernetes Service (AKS) clusters](/azure/aks/upgrade-cluster#upgrade-an-aks-cluster). |
| 18 | + |
| 19 | +## Symptoms |
| 20 | + |
| 21 | +When you try to upgrade an AKS cluster by using the Azure CLI, the upgrade operation is blocked and returns one or more of the following error messages. |
| 22 | + |
| 23 | +**Error message 1: K8sVersionNotSupported** |
| 24 | + |
| 25 | +> `<ClusterName>` is on version 1.25.6 which is not supported in this region. Please use the `[az aks get-versions]` command to get the supported version list in this region. For more information, see [Supported Kubernetes versions in Azure Kubernetes Service (AKS)](https://aka.ms/supported-version-list). |
| 26 | +
|
| 27 | +**Error message 2: OperationNotAllowed** |
| 28 | + |
| 29 | +> Upgrading Kubernetes version 1.24.9 to 1.26.6 is not allowed. Available upgrades: [1.29.15 1.29.14 1.29.13 1.29.12 1.29.11 1.29.10 1.29.9 1.29.8 1.29.7 1.29.6 1.29.5 1.29.4 1.29.2 1.29.0]. For more information, see [AKS supported Kubernetes versions](https://aka.ms/aks-supported-k8s-ver) for version details. |
| 30 | +
|
| 31 | +**Error message 3: NodePoolMcVersionIncompatible** |
| 32 | + |
| 33 | +> Node pool version 1.24.9 and control plane version 1.29.15 is incompatible. Minor version of node pool cannot be more than 3 versions less than control plane's version. Minor version of node pool is 24 and control plane is 29. For more information, see [AKS upgrade version skew policy](https://aka.ms/aks/UpgradeVersionRules). |
| 34 | +
|
| 35 | +## Cause |
| 36 | + |
| 37 | +The upgrade isn't allowed for one or more of the following reasons: |
| 38 | + |
| 39 | +- The target Kubernetes version (for example, 1.26 or 1.25) is no longer supported in the selected Azure region. |
| 40 | + |
| 41 | +- You aren't allowed to skip minor versions during upgrades (for example, from 1.24.*x* to 1.26.*x* or 1.27.*x*) unless the current version is unsupported. |
| 42 | + |
| 43 | +- A version skew between the control plane and node pool (**NodePoolMcVersionIncompatible**) occurs if you try to upgrade only the control plane. In this situation, the node pool version becomes more than three minor versions behind the control plane version. A gap of this size or greater causes the error. |
| 44 | + |
| 45 | +To understand more about these errors, refer to following articles: |
| 46 | + |
| 47 | +- [AKS supported Kubernetes versions](https://aka.ms/aks-supported-k8s-ver) |
| 48 | +- [AKS upgrade version skew policy](https://aka.ms/aks/UpgradeVersionRules) |
| 49 | + |
| 50 | +## Solution |
| 51 | + |
| 52 | +### Step 1: Verify the current version and available upgrade paths |
| 53 | + |
| 54 | +To view the current Kubernetes version and supported upgrade targets, run the following command: |
| 55 | + |
| 56 | +```azurecli |
| 57 | +az aks get-upgrades --resource-group <RG> --name <ClusterName> --output table |
| 58 | +``` |
| 59 | + |
| 60 | +If only newer versions, such as 1.29.*x*, are listed, and intermediate versions, such as 1.27.*x*, 1.26.*x*, or 1.25.*x*, are missing, this indicates that |
| 61 | +those versions are deprecated in your region. |
| 62 | + |
| 63 | +### Step 2: Try a full upgrade (control plane and node pool together) |
| 64 | + |
| 65 | +Because the version skew policy dictates that control planes can't be more than three minor versions ahead of node pools, |
| 66 | +a separate control-plane-only upgrade might not be allowed. Instead, upgrade both the control plane and node pool together: |
| 67 | + |
| 68 | +```azurecli |
| 69 | +az aks upgrade --resource-group <RG> --name <ClusterName> --kubernetes-version <available upgrade version> --yes |
| 70 | +``` |
| 71 | + |
| 72 | +This method makes sure that the following conditions apply: |
| 73 | + |
| 74 | +- You're in compliance with the version skew policy. |
| 75 | +- You use a supported Kubernetes version. |
| 76 | +- You upgrade both components in a coordinated manner. |
| 77 | + |
| 78 | +### Additional tips |
| 79 | + |
| 80 | +- Always validate supported versions in your region by using the following command: |
| 81 | + |
| 82 | +```azurecli |
| 83 | +az aks get-versions --location <region> --output table |
| 84 | +``` |
| 85 | + |
| 86 | +- Avoid trying to upgrade to deprecated versions. In this situation, AKS might enforce an immediate skip to a supported long-term version (for example, to version 1.29). |
| 87 | + |
| 88 | +- If AKS clusters are running outdated Kubernetes versions that violate the skew policy, the recommended best practices are as follows: |
| 89 | + |
| 90 | + - **Create a new cluster:** create an AKS cluster by using a supported Kubernetes version. |
| 91 | + |
| 92 | + - **Migrate workloads:** To make sure that your workloads run on supported versions, transfer them to the new cluster. |
| 93 | + |
| 94 | + - **Avoid upgrading across multiple versions:** Instead of upgrading through several minor versions, move to a new cluster to minimize complexity and avoid potential issues. |
| 95 | + |
| 96 | + - **Back up and validate data:** Make sure that all data is backed up and validated before a migration. |
| 97 | + |
| 98 | + - **Test thoroughly:** To identify and resolve any compatibility issues, perform thorough testing in a staging environment. |
| 99 | + |
| 100 | +[!INCLUDE [azure-help-support](../../../includes/azure-help-support.md)] |
0 commit comments