microsoft/aspire · error · InvalidOperationException

At least one gateway endpoint (HTTP or HTTPS) must be…

Error message

At least one gateway endpoint (HTTP or HTTPS) must be provided.

What it means

GatewayConfigurationBuilder.BuildConfigExpression generates the YARP/proxy configuration template and needs an origin endpoint to substitute for the origin token. This error is thrown when neither an HTTPS nor an HTTP gateway endpoint was supplied to the builder. Without an origin, no valid proxy configuration can be emitted.

Solutions

Add an HTTPS endpoint to the gateway resource: .WithHttpsEndpoint(port: ...).
Or add an HTTP endpoint: .WithHttpEndpoint(port: ...) if TLS termination happens elsewhere.
Verify the fluent chain registers the endpoint before the gateway configuration expression is built.
Inspect EmitProxyConfiguration call sites to confirm the correct resource with endpoints is passed in.

Example fix

// before
var gateway = builder.AddContainer("gateway", "yarp");
gateway.WithGatewayConfiguration(...); // no HTTP(S) endpoint

// after
var gateway = builder.AddContainer("gateway", "yarp")
    .WithHttpEndpoint(targetPort: 8080);
gateway.WithGatewayConfiguration(...);

Defensive patterns

Strategy: validation

Validate before calling

// Confirm the gateway resource has an http/https endpoint before building config
var gateway = builder.AddContainer("gateway", "yarp").WithHttpEndpoint(targetPort: 8080);

Try / catch

try { gateway.WithGatewayConfiguration(...); }
catch (InvalidOperationException ex) when (ex.Message.Contains("At least one gateway endpoint"))
{ logger.LogError(ex, "Gateway needs an http/https endpoint"); throw; }

Prevention

Register the gateway's HTTP(S) endpoint before any configuration emission.
Use WithHttpsEndpoint when TLS terminates at the gateway.
Double-check which resource instance the builder receives.

When it happens

Trigger: Calling EmitProxyConfiguration or EmitHostedProxyConfiguration through the Gateway configuration builder with only non-HTTP endpoints registered, or with no endpoint argument passed at all (both httpsEndpoint and httpEndpoint null).

Common situations: Registering the gateway resource with only tcp/custom-scheme endpoints; forgetting to call WithHttpEndpoint/WithHttpsEndpoint on the gateway resource before emitting configuration; passing the wrong resource into the builder.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Blazor/GatewayConfigurationBuilder.cs:272

        {
            ["webAssembly"] = new JsonObject
            {
                ["environment"] = environment
            }
        };

        var json = config.ToJsonString(s_jsonOptions);

        // The only literal { } in the output are structural JSON braces (we control
        // all string values and they contain no braces). Escape them for string.Format,
        // then swap the origin token for {0}.
        var format = json
            .Replace("{", "{{")
            .Replace("}", "}}")
            .Replace(OriginToken, "{0}");

        var originEndpoint = httpsEndpoint ?? httpEndpoint
            ?? throw new InvalidOperationException("At least one gateway endpoint (HTTP or HTTPS) must be provided.");

        var originRef = new GatewayOriginReference(originEndpoint);
        var builder = new ReferenceExpressionBuilder();
        var segments = format.Split("{0}");
        for (var i = 0; i < segments.Length; i++)
        {
            if (i > 0)
            {
                builder.AppendFormatted(originRef);
            }
            builder.AppendLiteral(segments[i]);
        }

        return builder.Build();
    }
}

View on GitHub (pinned to 25830f84bd)