microsoft/aspire · error · InvalidOperationException

A ChatCompletionsClient could not be configured. Ensure…

Error message

A ChatCompletionsClient could not be configured. Ensure valid connection information was provided in 'ConnectionStrings:{connectionName}' or specify a '{nameof(ChatCompletionsClientSettings.Endpoint)}' and optionally a '{nameof(ChatCompletionsClientSettings.Key)}' in the '{configurationSectionName}' configuration section.

What it means

AspireAzureAIInferenceExtensions.AddClient configures a ChatCompletionsClient lazily and throws InvalidOperationException at client creation time when settings.Endpoint is null — meaning no usable connection string or configured endpoint was found.

Solutions

Ensure 'ConnectionStrings:{connectionName}' exists and contains a valid endpoint (e.g. Endpoint=https://<resource>.services.ai.azure.com/models)
Or set Endpoint (and optionally Key) under the configuration section passed to the extension
If using Aspire hosting, add a WithReference(chatResource) so the connection string is injected

Example fix

// before
builder.AddChatCompletionsClient("chat"); // no such connection string
// after
builder.AddChatCompletionsClient("chat");
// with appsettings: "ConnectionStrings": { "chat": "Endpoint=https://myai.services.ai.azure.com/models;Key=..." }

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

Use WithReference in the AppHost so connection strings are injected
Verify ConnectionStrings entries exist in appsettings/environment before deployment
Keep endpoint connection string format matching Azure AI Inference expectations

When it happens

Trigger: Calling AddChatCompletionsClient/AddAzureAIInferenceClient with a connection name whose 'ConnectionStrings:{name}' entry is missing or unparseable, and no Endpoint in the '{configurationSectionName}' config section.

Common situations: Connection string not registered in appsettings or environment (common in Aspire when the resource isn't referenced); malformed connection string the parser couldn't map to an endpoint; running the app outside the AppHost without copying connection info.

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

Appendix: source

Thrown at src/Components/Aspire.Azure.AI.Inference/AspireAzureAIInferenceExtensions.cs:149

    private sealed class ChatCompletionsClientServiceComponent : AzureComponent<ChatCompletionsClientSettings, ChatCompletionsClient, AzureAIInferenceClientOptions>
    {
        // 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<ChatCompletionsClient, AzureAIInferenceClientOptions> AddClient(
            AzureClientFactoryBuilder azureFactoryBuilder,
            ChatCompletionsClientSettings settings,
            string connectionName, string
            configurationSectionName)
        {
            return azureFactoryBuilder.AddClient<ChatCompletionsClient, AzureAIInferenceClientOptions>((options, _, _) =>
            {
                if (settings.Endpoint is null)
                {
                    throw new InvalidOperationException($"A ChatCompletionsClient could not be configured. Ensure valid connection information was provided in 'ConnectionStrings:{connectionName}' or specify a '{nameof(ChatCompletionsClientSettings.Endpoint)}' and optionally a '{nameof(ChatCompletionsClientSettings.Key)}' in the '{configurationSectionName}' configuration section.");
                }
                else
                {
                    var endpoint = settings.Endpoint;

                    // Connect to Azure AI Foundry using key auth
                    if (!string.IsNullOrEmpty(settings.Key))
                    {
                        var credential = new AzureKeyCredential(settings.Key);
                        return new ChatCompletionsClient(endpoint, credential, options);
                    }
                    else
                    {
                        var credential = settings.TokenCredential ?? AzureCredentialHelper.CreateDefaultAzureCredential();

                        // Defines the scopes used for authorization when connecting to Azure AI Inference services.
                        // Use the default one (ml.azure.com) and add the public one required for Azure Foundry AI.
                        // If users want to use a different scope they can configure the option using the client builder.

View on GitHub (pinned to 25830f84bd)