microsoft/aspire · error

Azure CLI (az) not found. Install it from…

Error message

Azure CLI (az) not found. Install it from https://learn.microsoft.com/cli/azure/install-azure-cli

What it means

The AKS pipeline shells out to the Azure CLI, and FindAzCli could not find an 'az' executable on PATH. Every az-driven step (get-credentials, destroy credentials, etc.) requires the Azure CLI to be installed and discoverable.

Solutions

1. Install the Azure CLI: https://learn.microsoft.com/cli/azure/install-azure-cli
2. Verify with 'az --version' in the same shell/user context that launches the AppHost
3. If az is installed but not found, add its directory to PATH for the process (e.g. export PATH="$PATH:/usr/local/bin" or update the IDE/CI environment)
4. On CI, use the Azure CLI setup step/action before running the deploy

Example fix

// before
// $ az --version
// bash: az: command not found
// after
// $ curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
// $ az --version
// azure-cli 2.x.x

if (PathLookupHelper.FindFullPathFromPath("az") is null)
    throw new InvalidOperationException("Install the Azure CLI before deploying AKS environments.");

catch (InvalidOperationException ex) when (ex.Message.Contains("Azure CLI (az) not found"))
{
    // install the Azure CLI or fix PATH, then rerun
}

When it happens

Trigger: Any pipeline step resolving azPath runs on a machine/container where PathLookupHelper.FindFullPathFromPath("az") returns null — Azure CLI not installed, or PATH in the app host process lacks the az install location (common on CI agents or containers).

Common situations: Fresh CI agent or devcontainer without the Azure CLI; az installed only in a user profile dir not on PATH; running the AppHost from an IDE whose PATH differs from the shell.

Related errors

• AzureCliNotOnPathException (Azure CLI is not on PATH)
• Helm CLI not found or could not be invoked. Aspire requires…
• The 'rad' CLI was not found. Please install it from
• Aspire skills bundle contains an empty relative path.
• Cannot perform destructive operation without confirmation…

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/21d1675691c10653. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.Azure.Kubernetes/AzureKubernetesEnvironmentResource.AksPipeline.cs:735

                    "Ensure the AKS preview features 'Microsoft.ContainerService/AKSGatewayAPIPreview' and " +
                    "'Microsoft.ContainerService/AKSAppGatewayContainersPreview' are registered on the subscription, " +
                    "and that the AGC ALB controller add-on (ingressProfile.applicationLoadBalancer) finished installing.");
            }

            logger.LogDebug(
                "GatewayClass 'azure-alb-external' not yet available (attempt {Attempt}); retrying in {Delay}s",
                attempt, pollInterval.TotalSeconds);

            await Task.Delay(pollInterval, cancellationToken).ConfigureAwait(false);
        }
    }

    private static string FindAzCli()
    {
        var azPath = PathLookupHelper.FindFullPathFromPath("az");
        if (azPath is null)
        {
            throw new InvalidOperationException(
                "Azure CLI (az) not found. Install it from https://learn.microsoft.com/cli/azure/install-azure-cli");
        }
        return azPath;
    }

    /// <summary>
    /// Gets the subscription and resource group this resource explicitly targets, if any.
    /// </summary>
    /// <remarks>
    /// Mirrors the precedence in <c>BicepUtilities.GetExistingResourceScope</c>: an explicitly
    /// assigned <see cref="AzureBicepResource.Scope"/> (which <c>ConfigureInfrastructure</c> can set)
    /// wins over the <see cref="ExistingAzureResourceAnnotation"/> that <c>AsExistingInResourceGroup</c>
    /// and friends attach. The credential fetch has to agree with whatever the provisioner deployed
    /// against. Values are returned unresolved because they may be a literal string, a
    /// <see cref="ParameterResource"/>, or a <see cref="BicepOutputReference"/>.
    /// </remarks>
    private (object? Subscription, object? ResourceGroup) GetExplicitScopeValues()
    {

View on GitHub (pinned to 25830f84bd)