microsoft/aspire · error · InvalidOperationException

The gateway ' ' must define an HTTP or HTTPS endpoint.

Error message

The gateway '{gateway.Resource.Name}' must define an HTTP or HTTPS endpoint.

What it means

WithBlazorApp's environment callback needs a gateway endpoint (https preferred, else http) to point WASM clients at the gateway. If the gateway resource defines neither an http nor https endpoint, the callback throws an InvalidOperationException when configuring environment variables.

Solutions

Add an endpoint to the gateway: .WithHttpEndpoint() or .WithHttpsEndpoint().
Use AddBlazorGateway which configures endpoints for you.
Verify with gateway.Resource.EndpointCollection / annotations that http or https exists before calling WithBlazorApp.
Ensure endpoint names are exactly "http"/"https" since lookup is by scheme.

Example fix

// before
var gateway = builder.AddBlazorGateway("gateway", scriptPath);
// after
var gateway = builder.AddBlazorGateway("gateway", scriptPath).WithHttpEndpoint();

Defensive patterns

Strategy: validation

Validate before calling

var hasEndpoint = gateway.Resource.Annotations.OfType<EndpointAnnotation>()
    .Any(e => e.Scheme is "http" or "https");
if (!hasEndpoint) throw new InvalidOperationException("Gateway needs an http or https endpoint before WithBlazorApp.");

Try / catch

try { gateway.WithBlazorApp(app); } catch (InvalidOperationException ex) when (ex.Message.Contains("must define an HTTP or HTTPS endpoint")) { logger.LogError(ex, "Add WithHttpEndpoint/WithHttpsEndpoint to the gateway"); throw; }

Prevention

Always call WithHttpEndpoint/WithHttpsEndpoint on custom gateways.
Prefer AddBlazorGateway, which wires endpoints for you.
Add an AppHost startup assertion that the gateway exposes an endpoint.

When it happens

Trigger: Calling gateway.WithBlazorApp(...) on a gateway resource created without WithEndpoint/WithHttpEndpoint/WithHttpsEndpoint, then starting the app so the environment callback executes.

Common situations: Manually building a gateway resource and forgetting endpoints; renaming/removing endpoint definitions during refactoring; conditional endpoint registration that never runs.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Blazor/BlazorGatewayExtensions.cs:333

        // Get or create the annotation on the gateway resource
        var annotation = GetOrAddGatewayAppsAnnotation(gateway.Resource);

        var gatewayOutputRoot = Path.Combine(
            GetBlazorStorePath(gateway.ApplicationBuilder), "gateways", gateway.Resource.Name);

        if (!annotation.IsInitialized)
        {
            annotation.IsInitialized = true;
            MirrorGatewayStateToClients(gateway);

            gateway.WithEnvironment(async context =>
            {
                var registeredApps = GetRegisteredApps(gateway.Resource);
                var httpsGatewayEndpoint = GetEndpointIfDefined(gateway.Resource, "https");
                var httpGatewayEndpoint = GetEndpointIfDefined(gateway.Resource, "http");
                var gatewayEndpoint = httpsGatewayEndpoint ?? httpGatewayEndpoint
                    ?? throw new InvalidOperationException($"The gateway '{gateway.Resource.Name}' must define an HTTP or HTTPS endpoint.");

                // Resolve the HTTP OTLP endpoint for WASM client proxying.
                // WASM clients use HTTP/protobuf (not gRPC), so we need the HTTP endpoint.
                // First try to resolve from the dashboard resource model (handles randomized ports
                // and isolated mode). Fall back to configuration for cases where the dashboard
                // resource isn't in the model (e.g. external dashboard).
                var httpOtlpEndpointUrl = ResolveHttpOtlpEndpointUrl(context, gateway.ApplicationBuilder.Configuration);

                if (httpOtlpEndpointUrl is null && registeredApps.Any(a => a.ProxyBlazorTelemetry))
                {
                    context.Logger.LogWarning(
                        "OTLP telemetry proxying was requested but no dashboard HTTP endpoint could be resolved. " +
                        "WASM client telemetry will not be forwarded.");
                }

                if (context.ExecutionContext.IsPublishMode)
                {
                    ConfigurePublishEnvironment(context, registeredApps, gatewayEndpoint, httpGatewayEndpoint);

View on GitHub (pinned to 25830f84bd)