Merge pull request #21248 from MicrosoftDocs/main

Auto Publish – main to live - 2026-07-14 17:01 UTC

Author: learn-build-service-prod[bot]

AKS-Arc/TOC.yml

@@ -201,6 +201,8 @@
             items:
             - name: Issues after deleting storage volumes
               href: delete-storage-volume.md
+            - name: Kubernetes version image not ready
+              href: aks-arc-image-not-ready.md
           - name: Security
             items:
             - name: Entra authentication prompts when running kubectl

AKS-Arc/aks-arc-image-not-ready.md

@@ -0,0 +1,132 @@
+---
+title: Troubleshoot AKS on Azure Local issues when Kubernetes version image isn't ready
+description: Learn how to mitigate cluster and node pool issues when a Kubernetes version reports image not ready on AKS enabled by Azure Arc on Azure Local.
+ms.topic: troubleshooting
+author: davidsmatlak
+ms.author: davidsmatlak
+ms.date: 07/01/2026
+ms.reviewer: srikantsarwa
+
+# Intent: As an IT admin, I want to troubleshoot and resolve Kubernetes version image readiness issues in AKS on Azure Local.
+# Keyword: Kubernetes version image not ready AKS Azure Local
+---
+
+# Troubleshoot AKS on Azure Local issues when Kubernetes version image isn't ready
+
+This article describes how to mitigate cluster and node pool issues when a Kubernetes version reports image not ready on AKS enabled by Azure Arc on Azure Local.
+
+## Symptoms
+
+You might observe one or more of the following error scenarios when creating or updating an AKS Arc cluster:
+
+### Error 1: Gallery image not found during cluster creation
+
+```output
+Provisioning the AKSArc cluster. This operation might take a while...
+
+(ResourceDeploymentFailure) The resource write operation failed to complete successfully, because it reached terminal provisioning state 'Failed'.
+
+(ClusterPrecheckFailed) Error: Aks Arc cluster creation precheck failed. Detailed message: 1 error occurred:
+* rpc error: code = NotFound desc = Type[GalleryImage], Location[MocLocation], Name[linux-cblmariner-0.11.26.10605]: Not Found
+```
+
+### Error 2: Kubernetes version validation failure
+
+```output
+Provisioning the AKSArc cluster. This operation might take a while...
+
+(TemplateDeploymentValidationFailed) Validation failed for 'Microsoft.HybridContainerService/provisionedClusterInstances'.
+
+(PreflightValidationFailed) Preflight validation failed for one or more resources
+
+(PreflightValidationFailed) admission webhook "vhybridakscluster.kb.io" denied the request: {
+   "result": "Failed",
+   "validationChecks": [
+      {
+         "name": "K8sVersionValidation",
+         "message": "Kubernetes version 1.33.5 isn't ready for use on Linux. Please go to https://aka.ms/aksarccheckk8sversions for details of how to check the readiness of Kubernetes versions.",
+         "recommendation": "Please check https://aka.ms/AKSArcValidationErrors/K8sVersionValidation for recommendations"
+      }
+   ]
+}
+```
+
+For more information on troubleshooting the K8sVersionValidation error code, see [Troubleshoot K8sVersionValidation error code](cluster-k8s-version.md).
+
+## Cause
+
+It's possible that the image provisioning is still in progress. AKS on Azure Local depends on image readiness for the selected Kubernetes version and OS SKU. If the required image variant isn't fully provisioned or available, the Kubernetes version remains not ready and dependent operations can fail.
+
+## Workaround
+
+Use the following steps to recover image readiness.
+
+### 1. Verify available Kubernetes versions
+
+Run the following command to check available Kubernetes versions:
+
+```azurecli
+az aksarc get-versions --resource-group <resource-group-name> --custom-location <custom-location-name>
+```
+
+Confirm that your target version is listed and supported for your intended OS SKU.
+
+### 2. Check storage path health
+
+Run the following command to verify storage path status:
+
+```azurecli
+az stack-hci-vm storagepath list --resource-group <resource-group-name> --custom-location <custom-location-resource-id>
+```
+
+If the expected storage path is missing or unhealthy, recreate or update it by following the guidance in [Create storage path for Azure Local](/azure/azure-local/manage/create-storage-path).
+
+### 3. Refresh storage path metadata
+
+Run the following command to refresh the storage path:
+
+```azurecli
+az stack-hci-vm storagepath update --resource-group <resource-group-name> --custom-location <custom-location-resource-id> --name <storage-path-name> --location <azure-region>
+```
+
+This action can trigger revalidation and image resynchronization.
+
+### 4. Run support module validation
+
+Use the Support.AksArc diagnostic tool to validate that all tests are passing. For installation and usage instructions, see [Support.AksArc diagnostic and remediation tool](support-module.md).
+
+Ensure all validation checks pass before proceeding with cluster operations.
+
+### 5. Wait and retry the AKS operation
+
+After recovering the storage path and image sync, retry the failed cluster or node pool operation.
+
+### 6. If the issue persists
+
+If the problem continues after following the previous steps, collect diagnostic logs and open a support request.
+
+Include the following information:
+
+- Resource group
+- Custom location
+- Azure Local resource ID
+- Full error message
+- Correlation IDs from the error output
+
+## Prevention
+
+To prevent this issue:
+
+- Keep at least one storage path for AKS Arc cluster to work.
+- Validate storage path status is healthy (green status).
+- Never rename or change the folder path name locally on the Azure Local machine.
+- Avoid deleting storage volumes or storage paths used by AKS on Azure Local.
+- Validate storage path availability before cluster upgrades.
+- Use supported Kubernetes versions and OS SKUs for your target environment.
+- Apply platform updates and retry transient image provisioning states after a short interval.
+
+## Related content
+
+- [Troubleshoot AKS on Azure Local issues after deleting storage volumes](delete-storage-volume.md)
+- [Create storage path for Azure Local](/azure/azure-local/manage/create-storage-path)
+- [AKS Arc troubleshooting](aks-troubleshoot.md)

azure-local/small-form-factor/small-form-factor-faq.md

@@ -39,4 +39,4 @@ Run:
 az provisionedmachine reset-os --name <NAME_OF_MACHINE> --resource-group <RESOURCE_GROUP_NAME>
 ```
 
-After the reset finishes, you can provision the machine again by using either the Azure portal or the Azure CLI.
+After the reset finishes, you can provision the machine again by using either the Azure portal or the Azure CLI.

azure-local/small-form-factor/small-form-factor-known-issues.md

@@ -19,13 +19,13 @@ The following known issues apply to Azure Local small form factor deployments ru
 
 | Feature area | Issue | Impact | Workaround |
 |---|---|---|---|
-| Subscription setup | New required resource providers were added since the last release. | Deployment can fail if the required providers aren't registered. | Validate your subscription against the current required provider list before deployment. |
+| Subscription setup | New required resource providers were added since the last release. | Deployment can fail if the required providers aren't registered. | [Validate your subscription against the current required provider list before deployment](small-form-factor-subscription-setup.md#register-the-required-resource-providers). |
 | Subscription policy | Azure policies that restrict publicly accessible storage accounts can block deployment. | Provisioned machine creation can fail during storage account-related steps. | If you hit storage account errors, review subscription policies that restrict publicly accessible storage accounts. |
 | ROE install | NUC 15 Pro doesn't show status messages on the CLI during ROE install. | This behavior can be confusing during testing because the installation might appear stalled. | When you're testing on a NUC 15 Pro, treat a blank screen with a blinking cursor as a successful in-progress state. |
 | OS provisioning | During OS provisioning, the Azure portal may display the status **Action Required!** even though provisioning is progressing successfully. | Users may incorrectly assume that provisioning has failed and could file unnecessary support requests or ICMs. | No action is required. OS provisioning continues to run successfully despite the incorrect status message. Monitor the provisioning workflow until completion. |
-| OS provisioning | OS provisioning can intermittently fail because the `LinuxEdgeObservability` extension times out during deployment. The extension attempts to retrieve the GCS configuration file after observability tenant registration, which can take up to eight minutes. However, the Azure Arc extension manager imposes a five-minute timeout on the enable operation. | OS provisioning may intermittently fail during deployment. | Retry the OS provisioning operation. This issue is intermittent and occurs when the observability tenant registration exceeds the extension manager timeout window. |
+| OS provisioning | OS provisioning can intermittently fail because the `LinuxEdgeObservability` extension times out during deployment. The extension attempts to retrieve the GCS configuration file after observability tenant registration, which can take up to eight minutes. However, the Azure Arc extension manager imposes a five-minute timeout on the enable operation. | OS provisioning may intermittently fail during deployment. | [Retry the OS provisioning operation](../deploy/troubleshoot-simplified-machine-provisioning.md#reattempt-a-failed-os-provisioning). This issue is intermittent and occurs when the observability tenant registration exceeds the extension manager timeout window. |
 | Reset OS | After running `reset-os`, the provisioned machine state in the Azure portal may display as **Unknown** instead of a resetting state. | Users may be unsure whether the reset operation is progressing successfully. | This behavior is expected in version 2604. Reset status flows and reset operations are not yet fully supported in the Azure portal for small form factor deployments. The portal currently defaults unsupported states to **Unknown**. |
-| Retesting | TPM slot exhaustion can happen after repeated deployments, usually after about 15 runs. | Retesting can fail when no TPM slots remain. | Manually clear the TPM in BIOS before you retest. |
+| Retesting | TPM slot exhaustion can happen after repeated deployments, usually after about 15 runs. | Retesting can fail when no TPM slots remain. | [Manually clear the TPM in BIOS before you retest](small-form-factor-troubleshoot.md#tpm-isnt-writable-during-provisioning). |
 
 ## Related content