microsoft/aspire · error · InvalidOperationException

Gateway ' ' configures hostnames that would be inherited by…

Error message

Gateway '{gatewayResource.Name}' configures {resolvedHostnames.Count} hostnames that would be inherited by a hostless route, but Kubernetes Gateway API HTTPRoute.spec.hostnames supports at most {HttpRouteHostnameLimit} entries. Define explicit host-scoped routes with WithRoute(hostname, path, endpoint) so each HTTPRoute stays within the limit. See the Kubernetes Gateway API documentation: {HttpRouteSpecDocumentationUrl}

What it means

The Kubernetes environment thrower validates that a gateway's total resolved hostname set fits within the Kubernetes Gateway API limit (HTTPRoute.spec.hostnames supports at most HttpRouteHostnameLimit, typically 16). When a hostless route is present it would inherit every gateway hostname, so the combined set must stay within the limit. The library throws to prevent generating an invalid HTTPRoute that the Kubernetes API server would reject.

Solutions

1. Add host-scoped routes with WithRoute(hostname, path, endpoint) so no hostless route inherits all hostnames
2. Reduce the number of hostnames on the gateway (split across multiple gateways)
3. Remove unneeded WithHostname entries

Example fix

// before
gateway.WithRoute("/api", apiEndpoint); // hostless route inherits all 20 hostnames
// after
gateway.WithRoute("api.example.com", "/api", apiEndpoint); // per-host route stays within limit

// before deploy
gateway.EnsureHostlessRoutesFitHostnames(); // or check yourself:
if (hostnames.Count > 16 && routes.Any(r => r.Host is null))
    throw new InvalidOperationException("Add host-scoped routes or reduce hostnames.");

try { await deployAsync(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("HTTPRoute.spec.hostnames"))
{ logger.LogError(ex, "Too many gateway hostnames for a hostless route."); }

When it happens

Trigger: Calling AddKubernetesGateway with more than HttpRouteHostnameLimit hostnames resolved (explicitly via WithHostname or from listener hostnames) while at least one route was added without a host, i.e. WithRoute(path, endpoint) without a hostname argument.

Common situations: Large multi-tenant deployments with many custom domains attached to one gateway; discovery resolving many listener hostnames; developers forgetting to scope routes to hosts after adding hostnames incrementally.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Path must start with '/'.
• ASPIRERADIUS046
• ASPIRERADIUS061
• ASPIRERADIUS067
• Cannot derive a Helm release name from resource name

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

Appendix: source

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

        // This whole method re-runs when the deployment-target step executes a second time (once for
        // "before-start", once in the publish/deploy DAG). GeneratedGateway is assigned so it replaces
        // itself, but GeneratedHttpRoutes is appended to — without clearing, every route is emitted
        // twice and the chart renders duplicate HTTPRoute objects with identical names.
        gatewayResource.GeneratedHttpRoutes.Clear();

        var gateway = new GatewayV1
        {
            Metadata = { Name = gatewayName }
        };
        var resolvedHostnames = await ResolveHostnamesAsync(
            gatewayResource.Hostnames,
            gatewayResource.Name,
            cancellationToken).ConfigureAwait(false);

        if (resolvedHostnames.Count > HttpRouteHostnameLimit &&
            gatewayResource.Routes.Any(route => route.Host is null))
        {
            throw new InvalidOperationException(
                $"Gateway '{gatewayResource.Name}' configures {resolvedHostnames.Count} hostnames that would be inherited by a hostless route, " +
                $"but Kubernetes Gateway API HTTPRoute.spec.hostnames supports at most {HttpRouteHostnameLimit} entries. " +
                $"Define explicit host-scoped routes with WithRoute(hostname, path, endpoint) so each HTTPRoute stays within the limit. " +
                $"See the Kubernetes Gateway API documentation: {HttpRouteSpecDocumentationUrl}");
        }

        gateway.Spec.GatewayClassName = await ResolveExpressionAsync(gatewayResource.GatewayClassName, gatewayResource.Name, cancellationToken).ConfigureAwait(false);

        foreach (var (key, value) in gatewayResource.GatewayAnnotations)
        {
            gateway.Metadata.Annotations[key] = await ResolveExpressionAsync(value, gatewayResource.Name, cancellationToken).ConfigureAwait(false);
        }

        gateway.Spec.Listeners.Add(new GatewayListenerV1
        {
            Name = "http",
            Protocol = "HTTP",
            Port = 80,

View on GitHub (pinned to 25830f84bd)