microsoft/aspire · error

Timed out waiting for the 'azure-alb-external' GatewayClass…

Error message

Timed out waiting for the 'azure-alb-external' GatewayClass to appear in the cluster. 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.

What it means

The library polls for up to 10 minutes for the 'azure-alb-external' GatewayClass to appear in the AKS cluster after provisioning, and it never showed up. This GatewayClass is installed asynchronously by the AGC ALB controller add-on, and its absence means the required AKS preview features or the add-on did not activate.

Solutions

1. Register the preview features and reinstall the extension: az feature register --namespace Microsoft.ContainerService --name AKSGatewayAPIPreview az feature register --namespace Microsoft.ContainerService --name AKSAppGatewayContainersPreview az provider register --namespace Microsoft.ContainerService
2. Verify the cluster was created with ingressProfile.applicationLoadBalancer enabled; otherwise recreate it with the AGC add-on
3. Check add-on status: kubectl get pods -n azure-alb-system and az aks show to confirm provisioning state Succeeded
4. Wait and retry — a slow rollout can exceed the 10-minute budget; re-running the deploy resumes polling

Example fix

// before
// az feature list -o table | grep AKSGatewayAPIPreview   # NotRegistered
// after
// az feature register --namespace Microsoft.ContainerService --name AKSGatewayAPIPreview
// az feature register --namespace Microsoft.ContainerService --name AKSAppGatewayContainersPreview
// az provider register --namespace Microsoft.ContainerService

var classOutput = await RunKubectlAsync("get gatewayclass azure-alb-external -o name");
if (string.IsNullOrWhiteSpace(classOutput))
    Console.WriteLine("azure-alb-external GatewayClass not present yet; check preview features and add-on.");

catch (InvalidOperationException ex) when (ex.Message.Contains("azure-alb-external"))
{
    // register AKSGatewayAPIPreview and AKSAppGatewayContainersPreview, then redeploy
}

When it happens

Trigger: WaitForAzureAlbGatewayClassAsync polls 'kubectl get gatewayclass' until the deadline passes without seeing azure-alb-external, then throws.

Common situations: AKS preview features AKSGatewayAPIPreview / AKSAppGatewayContainersPreview not registered on the subscription; cluster created without ingressProfile.applicationLoadBalancer; slow add-on rollout exceeding 10 minutes; cluster in a failed provisioning state.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Cannot apply AGC ApplicationLoadBalancer CR for
• Could not resolve subnet ID for AGC load balancer
• az aks get-credentials failed
• az resource list failed
• az resource list failed while checking AKS cluster existence

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

Appendix: source

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

            int exitCode;
            await using (disposable.ConfigureAwait(false))
            {
                var result = await resultTask.WaitAsync(cancellationToken).ConfigureAwait(false);
                exitCode = result.ExitCode;
            }

            if (exitCode == 0)
            {
                logger.LogInformation(
                    "GatewayClass 'azure-alb-external' is available (after {Attempts} probe(s))",
                    attempt);
                return;
            }

            if (DateTime.UtcNow >= deadline)
            {
                throw new InvalidOperationException(
                    "Timed out waiting for the 'azure-alb-external' GatewayClass to appear in the cluster. " +
                    "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)

View on GitHub (pinned to 25830f84bd)