microsoft/aspire · error · InvalidOperationException

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

Error message

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

What it means

EnsureEnvironmentCallback in the hosted-Blazor path requires the host resource to expose an https or http endpoint so it can compute the URL handed to WASM clients. If neither scheme is defined, it throws an InvalidOperationException while configuring the host's environment.

Solutions

  1. Add .WithHttpEndpoint() or .WithHttpsEndpoint() to the Blazor host resource.
  2. Use the standard hosted Blazor extension that configures endpoints automatically.
  3. Confirm endpoint names/schemes are exactly "http"/"https" as GetEndpointIfDefined expects.
  4. Check EndpointCollection annotations on host.Resource before starting the app.

Example fix

// before
var host = builder.AddProject<Projects.Host>("host");
// after
var host = builder.AddProject<Projects.Host>("host").WithHttpEndpoint();
Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

When it happens

Trigger: ProxyBlazorService/ProxyBlazorTelemetry wiring runs host.WithEnvironment(...) on a Blazor host resource lacking both http and https endpoints; callback executes at app start.

Common situations: Host project created without WithHttpEndpoint/WithHttpsEndpoint; endpoints added conditionally; switching a host from https-only templates to custom endpoint configuration that dropped both schemes.

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/fc8989a5036c63c9. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.Blazor/BlazorHostedExtensions.cs:139

                host.ApplicationBuilder.OnBeforeStart(async (beforeStartEvent, cancellationToken) =>
                {
                    var logger = beforeStartEvent.Services
                        .GetRequiredService<ILoggerFactory>()
                        .CreateLogger(typeof(BlazorHostedExtensions));
                    annotation.DebuggerClientProjectPath = await ResolveBlazorWasmClientProjectPathAsync(
                        projectMetadata.ProjectPath,
                        logger,
                        cancellationToken).ConfigureAwait(false);
                });
            }
        }

        host.WithEnvironment(context =>
        {
            var httpsHostEndpoint = GetEndpointIfDefined(host.Resource, "https");
            var httpHostEndpoint = GetEndpointIfDefined(host.Resource, "http");
            var hostEndpoint = httpsHostEndpoint ?? httpHostEndpoint
                ?? throw new InvalidOperationException($"The host '{host.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.
            var httpOtlpEndpointUrl = BlazorGatewayExtensions.ResolveHttpOtlpEndpointUrl(context, host.ApplicationBuilder.Configuration);

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

            GatewayConfigurationBuilder.EmitHostedProxyConfiguration(
                context.EnvironmentVariables,
                hostEndpoint,
                httpHostEndpoint,
                $"{host.Resource.Name} (client)",
                annotation.Services,

View on GitHub (pinned to 25830f84bd)