microsoft/aspire · error · InvalidOperationException

ConnectionString is missing. It should be provided in…

Error message

ConnectionString is missing. It should be provided in 'ConnectionStrings:{connectionName}' or under the 'ConnectionString' key in '{defaultConfigSectionName}' or '{typeSpecificSectionName}' configuration section.

What it means

Shared validation used by Aspire client integrations: a connection string is required before a client can be created. When the value is null/whitespace (and this is not an EF design-time context where a connection string is legitimately absent), it throws listing every configuration location that could supply the value.

Solutions

Add ConnectionStrings:{connectionName} to appsettings.json, user secrets, or environment variables (ConnectionStrings__{connectionName}).
Provide the ConnectionString key in the component's configuration section if that path is supported.
Run through the Aspire AppHost with .WithReference(...) so the value is injected.
Verify the connection name string passed to the extension matches configuration exactly.

Example fix

// before
builder.AddSqlServerDbContext<SalesDbContext>("salesDb"); // no ConnectionStrings:salesDb

// after (appsettings.json)
// { "ConnectionStrings": { "salesDb": "Server=localhost;Database=Sales;Trusted_Connection=True" } }
builder.AddSqlServerDbContext<SalesDbContext>("salesDb");

Defensive patterns

Strategy: validation

Validate before calling

var cs = configuration.GetConnectionString(connectionName);
if (string.IsNullOrWhiteSpace(cs))
    throw new InvalidOperationException($"Missing connection string '{connectionName}'. Add ConnectionStrings:{connectionName} to configuration.");

Try / catch

try { builder.AddSqlServerDbContext<MyDbContext>(name); }
catch (InvalidOperationException ex) when (ex.Message.Contains("ConnectionString is missing"))
{ /* emit which config sources were checked; abort startup */ }

Prevention

Keep a single list of required connection names and validate all of them at startup.
Use ConnectionStrings__{name} environment variables in containers/CI.
Run services through the Aspire AppHost so connection strings are injected automatically.

When it happens

Trigger: Calling any AddXxx client extension whose connection string resolution (ConnectionStrings:{name} or {section}:ConnectionString) produced an empty value at registration/factory time while isEfDesignTime is false.

Common situations: Database-less EF tooling scenarios aside: running outside AppHost, missing appsettings in CI, renamed connection name, configuration root not loaded (e.g. wrong environment), empty string in user secrets.

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

Appendix: source

Thrown at src/Components/Common/ConnectionStringValidation.cs:16

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

namespace Aspire;

internal static class ConnectionStringValidation
{
    public static void ValidateConnectionString(string? connectionString, string connectionName, string defaultConfigSectionName, string? typeSpecificSectionName = null, bool isEfDesignTime = false)
    {
        if (string.IsNullOrWhiteSpace(connectionString) && !isEfDesignTime)
        {
            var errorMessage = (!string.IsNullOrEmpty(typeSpecificSectionName))
                ? $"ConnectionString is missing. It should be provided in 'ConnectionStrings:{connectionName}' or under the 'ConnectionString' key in '{defaultConfigSectionName}' or '{typeSpecificSectionName}' configuration section."
                : $"ConnectionString is missing. It should be provided in 'ConnectionStrings:{connectionName}' or under the 'ConnectionString' key in '{defaultConfigSectionName}' configuration section.";

            throw new InvalidOperationException(errorMessage);
        }
    }
}

View on GitHub (pinned to 25830f84bd)