microsoft/aspire · error · InvalidOperationException

An OpenAIClient could not be configured. Ensure valid…

Error message

An OpenAIClient could not be configured. Ensure valid connection information was provided in 'ConnectionStrings:{connectionName}' or specify a {nameof(settings.Key)} in the '{configurationSectionName}' configuration section.

What it means

The OpenAIClient factory throws when it cannot build a client: neither a connection string nor a settings.Key (via the configuration section) was available. The library fails fast rather than returning an unusable client.

Solutions

Add a connection string with the key, e.g. "openai": "Endpoint=https://api.openai.com;Key=sk-..." under ConnectionStrings
Set settings.Key via the configuration section, e.g. Aspire:OpenAI:ApiKey configuration or settings callback in AddOpenAIClient
Verify the connection name matches between AddOpenAIClient and configuration
Ensure the AppHost resource reference injects the connection string in the dev/deployed environment

Example fix

// before
builder.AddOpenAIClient("openai"); // nothing configured
// after
// appsettings.json / user-secrets:
// { "ConnectionStrings": { "openai": "Endpoint=https://api.openai.com;Key=sk-..." } }
builder.AddOpenAIClient("openai");
// or
builder.AddOpenAIClient("openai", settings => settings.Key = "sk-...");

Defensive patterns

Strategy: validation

Validate before calling

var cs = builder.Configuration.GetConnectionString("openai");
var key = builder.Configuration["Aspire:OpenAI:ApiKey"];
if (string.IsNullOrEmpty(cs) && string.IsNullOrEmpty(key))
    throw new InvalidOperationException("OpenAI requires a connection string or Aspire:OpenAI:ApiKey.");

Try / catch

try
{
    builder.AddOpenAIClient("openai");
}
catch (InvalidOperationException ex) when (ex.Message.Contains("An OpenAIClient could not be configured"))
{
    logger.LogError(ex, "No OpenAI connection string or API key configured.");
    throw;
}

Prevention

Reference the OpenAI hosting resource from the AppHost so the connection string is injected
Store the key in user-secrets/Key Vault with a startup validation check
Verify connection names and config section names match exactly

When it happens

Trigger: Registering AddOpenAIClient("openai") with no 'ConnectionStrings:openai' entry and no ApiKey under the 'Aspire:OpenAI' configuration section; settings.Key remains null in the factory delegate.

Common situations: Missing OPENAI_API_KEY / configuration in a deployed environment; running the client project without an AppHost reference; typo in the connection name or config section; secrets not loaded from user-secrets or Key Vault.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

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

Appendix: source

Thrown at src/Components/Aspire.OpenAI/AspireOpenAIExtensions.cs:140

            builder.Services.AddOpenTelemetry()
                .WithMetrics(b => b.AddMeter(telemetrySources));
        }

        return new AspireOpenAIClientBuilder(builder, connectionName, serviceKey, settings.DisableTracing, settings.EnableSensitiveTelemetryData);

        OpenAIClient ConfigureOpenAI(IServiceProvider serviceProvider)
        {
            if (settings.Key is not null)
            {
                var options = serviceKey is null ?
                    serviceProvider.GetRequiredService<IOptions<OpenAIClientOptions>>().Value :
                    serviceProvider.GetRequiredService<IOptionsMonitor<OpenAIClientOptions>>().Get(serviceKey);

                return new OpenAIClient(new ApiKeyCredential(settings.Key), options);
            }
            else
            {
                throw new InvalidOperationException(
                        $"An OpenAIClient could not be configured. Ensure valid connection information was provided in 'ConnectionStrings:{connectionName}' or " +
                        $"specify a {nameof(settings.Key)} in the '{configurationSectionName}' configuration section.");
            }
        }
    }
}

View on GitHub (pinned to 25830f84bd)