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(AzureOpenAISettings.Endpoint)}' or '{nameof(AzureOpenAISettings.Key)}' in the '{configurationSectionName}' configuration section.

What it means

AspireAzureOpenAIExtensions.AddClient throws InvalidOperationException when AzureOpenAISettings.Endpoint is null at client creation, meaning neither the connection string nor the config section yielded an endpoint (or key-only credential info).

Solutions

  1. Provide 'ConnectionStrings:{connectionName}' with Endpoint=https://<resource>.openai.azure.com/ (and Key if using key auth)
  2. Or set Endpoint and Key under the '{configurationSectionName}' section
  3. Add WithReference(azureOpenAI) in the AppHost so connection info is injected

Example fix

// before
builder.AddAzureOpenAIClient("openai"); // no connection string
// after
// appsettings: "ConnectionStrings": { "openai": "Endpoint=https://myres.openai.azure.com/;Key=..." }
builder.AddAzureOpenAIClient("openai");
Defensive patterns

Strategy: validation

Validate before calling

var cs = builder.Configuration.GetConnectionString("openai");
if (string.IsNullOrEmpty(cs) && builder.Configuration["Aspire:Azure:AI:OpenAI:Endpoint"] is null)
    throw new InvalidOperationException("No Azure OpenAI endpoint configured.");

Try / catch

try { var client = serviceProvider.GetRequiredService<AzureOpenAIClient>(); }
catch (InvalidOperationException ex) { logger.LogError(ex, "AzureOpenAIClient not configured"); }

Prevention

When it happens

Trigger: AddAzureOpenAIClient called with a connection name that has no 'ConnectionStrings:{name}' entry, or an unparseable entry, and no Endpoint in '{configurationSectionName}'.

Common situations: AppHost resource not referenced (no injected connection string); appsettings missing the Azure OpenAI section; running outside Aspire without providing endpoint+key; connection string format the parser doesn't recognize (e.g. bare key without IsAzure flag).

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

Appendix: source

Thrown at src/Components/Aspire.Azure.AI.OpenAI/AspireAzureOpenAIExtensions.cs:101

    }

    private sealed class OpenAIComponent : AzureComponent<AzureOpenAISettings, AzureOpenAIClient, AzureOpenAIClientOptions>
    {
        // GenAI telemetry isn't stable so MEAI currently has source name of "Experimental.Microsoft.Extensions.AI".
        // Listen to both names to ensure we capture telemetry from both stable and experimental versions.
        // When MEAI removes experimental from the source name, Aspire will continue to work without changes.
        protected override string[] ActivitySourceNames => ["Experimental.Microsoft.Extensions.AI", "Microsoft.Extensions.AI"];
        protected override string[] MetricSourceNames => ["Experimental.Microsoft.Extensions.AI", "Microsoft.Extensions.AI"];

        protected override IAzureClientBuilder<AzureOpenAIClient, AzureOpenAIClientOptions> AddClient(
            AzureClientFactoryBuilder azureFactoryBuilder, AzureOpenAISettings settings, string connectionName,
            string configurationSectionName)
        {
            return azureFactoryBuilder.AddClient<AzureOpenAIClient, AzureOpenAIClientOptions>((options, _, _) =>
            {
                if (settings.Endpoint is null)
                {
                    throw new InvalidOperationException($"An OpenAIClient could not be configured. Ensure valid connection information was provided in 'ConnectionStrings:{connectionName}' or specify a '{nameof(AzureOpenAISettings.Endpoint)}' or '{nameof(AzureOpenAISettings.Key)}' in the '{configurationSectionName}' configuration section.");
                }
                else
                {
                    // Connect to Azure OpenAI

                    if (!string.IsNullOrEmpty(settings.Key))
                    {
                        var credential = new ApiKeyCredential(settings.Key);
                        return new AzureOpenAIClient(settings.Endpoint, credential, options);
                    }
                    else
                    {
                        return new AzureOpenAIClient(settings.Endpoint, settings.Credential ?? AzureCredentialHelper.CreateDefaultAzureCredential(), options);
                    }
                }
            });
        }

View on GitHub (pinned to 25830f84bd)