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}'.

What it means

IsAzureConnectionString (used by AddOpenAIClientFromConfiguration / AddKeyedOpenAIClientFromConfiguration in the configurable OpenAI extension) throws InvalidOperationException when the connection string provides neither a service URI nor an API key — there is not enough information to construct an OpenAIClient.

Solutions

Add 'Endpoint=https://api.openai.com/v1' (or a service URI) or 'Key=...' (or both) to 'ConnectionStrings:{connectionName}'
Fix key names in the connection string — the parser looks for a URI and a key entry
Verify the env var/config backing the connection string is actually populated at runtime

Example fix

// before
"ConnectionStrings": { "openai": "" }
// after
"ConnectionStrings": { "openai": "Endpoint=https://api.openai.com/v1;Key=sk-..." }

Defensive patterns

Strategy: validation

Validate before calling

var cs = builder.Configuration.GetConnectionString("openai");
if (string.IsNullOrWhiteSpace(cs) || !(cs.Contains("Endpoint=") || cs.Contains("Key=")))
    throw new InvalidOperationException("Connection string must include Endpoint and/or Key.");

Try / catch

try { builder.AddOpenAIClientFromConfiguration("openai"); }
catch (InvalidOperationException ex) { logger.LogError(ex, "OpenAI connection string lacks endpoint/key"); }

Prevention

Include at least 'Key=...' or 'Endpoint=...' in every OpenAI connection string
Validate substituted env vars are non-empty before launch
Use the Azure-specific extension when the connection string comes from an Azure OpenAI resource

When it happens

Trigger: Passing a connection string that contains only unrelated keys (or is empty) to AddOpenAIClientFromConfiguration, so neither a Uri-valued entry nor a Key entry is found.

Common situations: Empty or placeholder connection string in appsettings; wrong key names (e.g. 'Token' instead of 'Key'); connection string copied from Azure OpenAI docs but used with the non-Azure configurable extension expecting Uri/Key; missing environment variable substituted into the string.

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

Appendix: source

Thrown at src/Components/Aspire.Azure.AI.OpenAI/AspireConfigurableOpenAIExtensions.cs:96

        var connectionBuilder = new DbConnectionStringBuilder
        {
            ConnectionString = connectionString
        };

        if (connectionBuilder.TryGetValue(ConnectionStringEndpoint, out var endpoint) && endpoint != null && Uri.TryCreate(endpoint.ToString(), UriKind.Absolute, out var endpointUri))
        {
            serviceUri = endpointUri;
        }

        if (connectionBuilder.TryGetValue(ConnectionStringKey, out var key) && key != null)
        {
            apiKey = key.ToString()?.Trim();
        }

        if (serviceUri == null && string.IsNullOrEmpty(apiKey))
        {
            throw new InvalidOperationException($"An OpenAIClient could not be configured. Ensure valid connection information was provided in 'ConnectionStrings:{connectionName}'.");
        }

        if (connectionBuilder.ContainsKey(ConnectionStringIsAzure))
        {
            return bool.TryParse(connectionBuilder[ConnectionStringIsAzure].ToString(), out var isAzure) && isAzure;
        }

        if (serviceUri != null && serviceUri.Host.Contains(".azure.", StringComparison.OrdinalIgnoreCase))
        {
            return true;
        }

        return false;
    }
}

View on GitHub (pinned to 25830f84bd)