microsoft/aspire · error · InvalidOperationException

Unable to add a Seq health check because the 'ServerUrl'…

Error message

Unable to add a Seq health check because the 'ServerUrl' setting is missing.

What it means

Aspire registers a Seq health check pointing at the Seq server URL. If SeqSettings.ServerUrl is null/missing after configuration binding, the health check cannot be constructed and Aspire throws instead of registering a broken check.

Solutions

Provide a connection string for the connection name: ConnectionStrings:seq = http://localhost:5341.
Set 'Aspire:Seq:ServerUrl' in configuration if not using a connection string.
If using the AppHost, add .WithReference(seq) to the project so the URL is injected.

Example fix

// before
builder.AddSeqEndpoint("seq"); // no ConnectionStrings:seq

// after (appsettings.json)
// { "ConnectionStrings": { "seq": "http://localhost:5341" } }
builder.AddSeqEndpoint("seq");

Defensive patterns

Strategy: validation

Validate before calling

var seqUrl = builder.Configuration.GetConnectionString("seq") ?? builder.Configuration["Aspire:Seq:ServerUrl"];
if (string.IsNullOrEmpty(seqUrl))
    throw new InvalidOperationException("Seq ServerUrl missing: set ConnectionStrings:seq or Aspire:Seq:ServerUrl before AddSeqEndpoint.");

Try / catch

try { builder.AddSeqEndpoint("seq"); }
catch (InvalidOperationException ex) when (ex.Message.Contains("ServerUrl"))
{ /* log: Seq health check skipped due to missing configuration */ }

Prevention

Inject the Seq URL via the AppHost (WithReference) rather than manual config when possible.
Include ConnectionStrings:seq in every environment's configuration checklist.
Validate required connection strings at startup before health check registration.

When it happens

Trigger: Calling AddSeqEndpoint when configuration provides neither a ConnectionStrings:{name} entry (which binds to ServerUrl) nor 'Aspire:Seq:ServerUrl', leaving settings.ServerUrl null.

Common situations: Hosting-only usage where the connection string was never injected (running app outside AppHost), renamed connection name, appsettings missing in the environment, Seq settings section deleted during refactoring.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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

Appendix: source

Thrown at src/Components/Aspire.Seq/AspireSeqExtensions.cs:92

            _ => settings.Traces.ExportProcessorType switch
            {
                ExportProcessorType.Batch => new BatchActivityExportProcessor(new OtlpTraceExporter(settings.Traces)),
                _ => new SimpleActivityExportProcessor(new OtlpTraceExporter(settings.Traces))
            }));

        if (!settings.DisableHealthChecks)
        {
            if (settings.ServerUrl is not null)
            {
                builder.TryAddHealthCheck(new HealthCheckRegistration(
                    "Seq",
                    _ => new SeqHealthCheck(settings.ServerUrl),
                    failureStatus: default,
                    tags: default));
            }
            else
            {
                throw new InvalidOperationException(
                    "Unable to add a Seq health check because the 'ServerUrl' setting is missing.");
            }
        }

    }
}

View on GitHub (pinned to 25830f84bd)