microsoft/aspire · error · InvalidOperationException

Gateway ' ' was not assigned a hostname address within the…

Error message

Gateway '{gatewayName}' was not assigned a hostname address within the discovery timeout. TLS hostname discovery cannot complete. Either retry the deploy (the controller may still be provisioning the address) or set an explicit hostname via WithHostname().

What it means

During deployment, TLS hostname discovery waits for the Gateway's provisioned address (from the gateway controller) within a timeout. If no address appears, no certificate can be issued for the HTTPS listener (cert-manager issues no cert for a hostname-less listener), so the deploy fails visibly instead of silently producing a non-functional gateway.

Solutions

Retry the deploy — the controller may still be provisioning the address
Set an explicit hostname via WithHostname() (or WithTls(hostname: ...)) to skip discovery
Verify the Gateway API controller is installed and healthy and that the Gateway's status is being populated
Check controller logs/events for provisioning failures

Example fix

// before
var gateway = env.AddKubernetesGateway("gw").WithTls();
// after
var gateway = env.AddKubernetesGateway("gw").WithTls(hostname: "app.example.com"); // or .WithHostname("app.example.com")

Defensive patterns

Strategy: retry

Validate before calling

// before deploy: ensure an explicit hostname is set for TLS gateways
if (tlsEnabled && string.IsNullOrEmpty(explicitHostname))
    logger.LogWarning("No explicit TLS hostname; discovery may time out on slow controllers.");

Try / catch

try { await deployAsync(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("hostname address within the discovery timeout"))
{ logger.LogError(ex, "Gateway address not assigned in time; retry or set WithHostname()."); }

Prevention

Set an explicit hostname via WithHostname()/WithTls(hostname:) for TLS gateways in environments with slow LB provisioning
Ensure the Gateway API controller is installed before deploying
Pre-provision/wait for the load balancer before running the deploy
Increase tolerance by retrying the deploy once before changing config

When it happens

Trigger: Deploying a Kubernetes environment with a TLS-enabled gateway where the controller (e.g. an LB implementation) is slow or fails to assign an address within the discovery timeout, and no explicit hostname was provided via WithHostname().

Common situations: Slow cloud load-balancer provisioning (e.g. fresh clusters where the LB takes minutes); controller crashes or misconfiguration (no GatewayClass controller installed); network/RBAC issues preventing the controller from updating the Gateway status.

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.

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.
Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Kubernetes/KubernetesEnvironmentResource.cs:1448

            // We use -o json and parse the full status to select Hostname-type addresses,
            // since some controllers return IP addresses which are not valid for TLS hostnames.
            context.Logger.LogInformation(
                "Waiting for Gateway '{GatewayName}' to be assigned a hostname address...", gatewayName);

            var discoveredFqdn = await DiscoverGatewayFqdnAsync(
                gatewayName, @namespace, environment, context).ConfigureAwait(false);

            if (string.IsNullOrEmpty(discoveredFqdn))
            {
                // Hard failure rather than a logged warning: when the user has TLS configured
                // without an explicit hostname, the deployment is only meaningful once the
                // listener hostname is patched (cert-manager's gateway shim issues no
                // certificate for a hostname-less HTTPS listener). Silently continuing
                // produces an apparently-successful deploy that never serves valid TLS, which
                // is far worse than failing visibly here. The user can fix this by either
                // waiting for their controller to assign an address sooner or by passing an
                // explicit hostname via WithHostname() / WithTls(hostname: ...).
                throw new InvalidOperationException(
                    $"Gateway '{gatewayName}' was not assigned a hostname address within the discovery timeout. " +
                    "TLS hostname discovery cannot complete. Either retry the deploy (the controller may still be " +
                    "provisioning the address) or set an explicit hostname via WithHostname().");
            }

            context.Logger.LogInformation(
                "Gateway '{GatewayName}' assigned address: {Fqdn}. Patching HTTPS listener(s) and bootstrapping TLS.",
                gatewayName, discoveredFqdn);

            // Find HTTPS listeners without a hostname by parsing the full Gateway JSON.
            var httpsListenerIndices = await FindHostnamelessHttpsListeners(
                gatewayName, @namespace, environment, context).ConfigureAwait(false);

            if (httpsListenerIndices.Count == 0)
            {
                context.Logger.LogWarning(
                    "No HTTPS listeners without hostname found on Gateway '{GatewayName}'. Skipping hostname patch.",
                    gatewayName);

View on GitHub (pinned to 25830f84bd)