microsoft/aspire · error · InvalidOperationException

A SearchIndexClient could not be configured. Ensure valid…

Error message

A SearchIndexClient could not be configured. Ensure valid connection information was provided in 'ConnectionStrings:{connectionName}' or specify an '{nameof(AzureSearchSettings.Endpoint)}' in the '{configurationSectionName}' configuration section.

What it means

Aspire's Azure AI Search integration throws this when AzureSearchSettings.Endpoint is null and no connection string provided one. A SearchIndexClient needs either an endpoint (with a credential) or a connection string; without either the client cannot be constructed. The library fails fast at client-creation time instead of letting the Azure SDK throw a less clear error.

Solutions

Add a connection string entry: "ConnectionStrings": { "search": "Endpoint=https://<account>.search.windows.net/" }
Set the Endpoint in the config section: "Aspire:Azure:Search:Documents": { "Endpoint": "https://<account>.search.windows.net/" }
Set it in code via configureSettings: settings.Endpoint = new Uri("https://<account>.search.windows.net")
Confirm the connectionName argument matches the key in ConnectionStrings

Example fix

// before
"ConnectionStrings": {}
// after
"ConnectionStrings": {
  "search": "Endpoint=https://mysearch.search.windows.net/"
}
// and register with builder.AddAzureSearchClient("search");

Defensive patterns

Strategy: validation

Validate before calling

if (builder.Configuration.GetConnectionString("search") is null &&
    builder.Configuration["Aspire:Azure:Search:Documents:Endpoint"] is null)
    throw new InvalidOperationException("Provide ConnectionStrings:search or Aspire:Azure:Search:Documents:Endpoint.");

Prevention

Register the connection string via WithReference in the AppHost rather than hand-editing config
Keep connectionName arguments identical to resource names
Validate required config at startup with a fail-fast check

When it happens

Trigger: Calling builder.AddAzureSearchClient(...) with no 'ConnectionStrings:<connectionName>' entry and no 'Aspire:Azure:Search:Documents:Endpoint' (or Endpoint set via configureSettings).

Common situations: Connection string not added to appsettings.json or user secrets; resource named differently in the connection string dictionary than the connectionName passed to AddAzureSearchClient; using endpoint-only auth but forgetting the Endpoint key when switching from key-based auth.

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

Appendix: source

Thrown at src/Components/Aspire.Azure.Search.Documents/AspireAzureSearchExtensions.cs:81

        new AzureSearchComponent().AddClient(builder, DefaultConfigSectionName, configureSettings, configureClientBuilder, connectionName: name, serviceKey: name);
    }

    private sealed class AzureSearchComponent : AzureComponent<AzureSearchSettings, SearchIndexClient, SearchClientOptions>
    {
        // `SearchIndexClient` is in the Azure.Search.Documents.Indexes namespace
        // but uses `SearchClientOptions` which is in the Azure.Search.Documents namespace
        // https://github.com/Azure/azure-sdk-for-net/blob/bed506dee05319ff2de27ca98500daa10573fe7d/sdk/search/Azure.Search.Documents/src/Indexes/SearchIndexClient.cs#L92
        protected override string[] ActivitySourceNames => ["Azure.Search.Documents.*"];

        protected override IAzureClientBuilder<SearchIndexClient, SearchClientOptions> AddClient(
            AzureClientFactoryBuilder azureFactoryBuilder, AzureSearchSettings settings, string connectionName,
            string configurationSectionName)
        {
            return azureFactoryBuilder.AddClient<SearchIndexClient, SearchClientOptions>((options, _, _) =>
            {
                if (settings.Endpoint is null)
                {
                    throw new InvalidOperationException($"A SearchIndexClient could not be configured. Ensure valid connection information was provided in 'ConnectionStrings:{connectionName}' or specify an '{nameof(AzureSearchSettings.Endpoint)}' in the '{configurationSectionName}' configuration section.");
                }

                if (!string.IsNullOrWhiteSpace(settings.Key))
                {
                    return new SearchIndexClient(settings.Endpoint, new AzureKeyCredential(settings.Key), options);
                }
                else
                {
                    return new SearchIndexClient(settings.Endpoint, settings.Credential ?? AzureCredentialHelper.CreateDefaultAzureCredential(), options);
                }
            });
        }

        protected override void BindClientOptionsToConfiguration(IAzureClientBuilder<SearchIndexClient, SearchClientOptions> clientBuilder, IConfiguration configuration)
        {
#pragma warning disable IDE0200 // Remove unnecessary lambda expression - needed so the ConfigBinder Source Generator works
            clientBuilder.ConfigureOptions(options => configuration.Bind(options));
#pragma warning restore IDE0200

View on GitHub (pinned to 25830f84bd)