What causes "Configuration section '{section}' not found" in microsoft/semantic-kernel?

Set the OpenAI API key via .NET user-secrets: 'dotnet user-secrets set "OpenAI:ApiKey" ' in the sample project, or add it to appsettings.json / TestConfiguration.

microsoft/semantic-kernel · error · ConfigurationNotFoundException

Configuration section '{section}' not found

Error message

Configuration section '{section}' not found

What it means

Thrown by the sample's constructor when the OpenAI/Azure OpenAI API key resolves to null while UseOpenAIConfig is true. It uses the single-argument ConfigurationNotFoundException constructor, so the entire 'OpenAI:ApiKey' string is reported as a configuration section, signaling that required test configuration is missing.

Source

Thrown at dotnet/samples/GettingStartedWithAgents/Step10_MultiAgent_Declarative.cs:95

        }
        finally
        {
            var azureaiAgent = agent as AzureAIAgent;
            Assert.NotNull(azureaiAgent);
            await azureaiAgent.Client.Administration.DeleteAgentAsync(azureaiAgent.Id);

            if (agentThread is not null)
            {
                await agentThread.DeleteAsync();
            }
        }
    }

    public Step10_MultiAgent_Declarative(ITestOutputHelper output) : base(output)
    {
        var openaiClient =
           this.UseOpenAIConfig ?
               OpenAIAssistantAgent.CreateOpenAIClient(new ApiKeyCredential(this.ApiKey ?? throw new ConfigurationNotFoundException("OpenAI:ApiKey"))) :
               !string.IsNullOrWhiteSpace(this.ApiKey) ?
                   OpenAIAssistantAgent.CreateAzureOpenAIClient(new ApiKeyCredential(this.ApiKey), new Uri(this.Endpoint!)) :
                   OpenAIAssistantAgent.CreateAzureOpenAIClient(new AzureCliCredential(), new Uri(this.Endpoint!));

        var agentsClient = AzureAIAgent.CreateAgentsClient(TestConfiguration.AzureAI.Endpoint, new AzureCliCredential());

        var builder = Kernel.CreateBuilder();
        builder.Services.AddSingleton<OpenAIClient>(openaiClient);
        builder.Services.AddSingleton<PersistentAgentsClient>(agentsClient);
        AddChatCompletionToKernel(builder);
        this._kernel = builder.Build();

        this._kernelAgentFactory =
            new AggregatorAgentFactory(
                new ChatCompletionAgentFactory(),
                new OpenAIAssistantAgentFactory(),
                new AzureAIAgentFactory());
    }

View on GitHub (pinned to c028a0c7dc)

Solutions

Set the OpenAI API key via .NET user-secrets: 'dotnet user-secrets set "OpenAI:ApiKey" <key>' in the sample project, or add it to appsettings.json / TestConfiguration.
If targeting Azure OpenAI, ensure UseOpenAIConfig is false and ApiKey (or Azure CLI credential) + Endpoint are configured.
Verify the configuration provider is loaded in BaseTest so TestConfiguration populates this.ApiKey before the constructor runs.

Example fix

// before
OpenAIAssistantAgent.CreateOpenAIClient(new ApiKeyCredential(this.ApiKey ?? throw new ConfigurationNotFoundException("OpenAI:ApiKey")))
// after - guard explicitly and give an actionable message
if (string.IsNullOrWhiteSpace(this.ApiKey))
    throw new ConfigurationNotFoundException("OpenAI", "ApiKey");
OpenAIAssistantAgent.CreateOpenAIClient(new ApiKeyCredential(this.ApiKey!));

Defensive patterns

Strategy: validation

Validate before calling

string apiKey = config["OpenAI:ApiKey"];
if (string.IsNullOrWhiteSpace(apiKey))
    throw new ConfigurationNotFoundException("OpenAI", "ApiKey");
// proceed to construct the sample

Try / catch

try { var sample = new Step10_MultiAgent_Declarative(output); }
catch (ConfigurationNotFoundException ex) when (ex.Section == "OpenAI:ApiKey")
    { Console.Error.WriteLine("Set 'OpenAI:ApiKey' via user-secrets."); }

Prevention

Run 'dotnet user-secrets init' then 'dotnet user-secrets set "OpenAI:ApiKey" <key>' in each sample project.
Fail fast on missing configuration in startup, before constructing clients.
Keep a checklist of required keys per sample in the repo README.

When it happens

Trigger: Constructing Step10_MultiAgent_Declarative with UseOpenAIConfig == true and this.ApiKey null/whitespace; i.e. the test/appsettings configuration did not supply an OpenAI API key.

Common situations: Running the GettingStarted samples locally without setting user-secrets or appsettings 'OpenAI:ApiKey'; CI without configured secrets; cloning the repo and expecting samples to run without configuration.

Related errors

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/e9d244ab7f00edfc. Report an issue: GitHub.