microsoft/aspire · error · InvalidOperationException

A QdrantClient could not be configured. Ensure valid…

Error message

A QdrantClient could not be configured. Ensure valid connection information was provided in 'ConnectionStrings:{connectionName}' or either {nameof(settings.Endpoint)} must be provided in the '{DefaultConfigSectionName}' or '{DefaultConfigSectionName}:{connectionName}' configuration section.

What it means

Aspire builds a QdrantClient either from a connection string or from an explicit Endpoint in configuration. When neither the 'ConnectionStrings:{name}' entry nor the settings' Endpoint property yields a usable endpoint, the client factory throws because there is no way to reach the Qdrant server.

Solutions

Add a valid connection string: ConnectionStrings:qdrant = http://localhost:6334 (gRPC/HTTP endpoint URI).
Set the Endpoint in configuration under 'Aspire:Qdrant:Client' or 'Aspire:Qdrant:Client:{connectionName}'.
Run through the Aspire AppHost (or WithReference(qdrant)) so the connection string is injected automatically.
Verify the connection name passed to AddQdrantClient matches the configuration key exactly (case-insensitive but must exist).

Example fix

// before
builder.AddQdrantClient("qdrant"); // no ConnectionStrings:qdrant, no endpoint config

// after (appsettings.json)
// { "ConnectionStrings": { "qdrant": "http://localhost:6334" } }
builder.AddQdrantClient("qdrant");

Defensive patterns

Strategy: validation

Validate before calling

var cs = builder.Configuration.GetConnectionString("qdrant");
var endpoint = builder.Configuration["Aspire:Qdrant:Client:Endpoint"];
if (string.IsNullOrEmpty(cs) && string.IsNullOrEmpty(endpoint))
    throw new InvalidOperationException("Qdrant connection string or Aspire:Qdrant:Client:Endpoint must be configured.");

Try / catch

try { builder.AddQdrantClient("qdrant"); }
catch (InvalidOperationException ex) when (ex.Message.Contains("QdrantClient could not be configured"))
{ /* surface config-missing guidance to ops */ }

Prevention

Always run Qdrant clients through the Aspire AppHost with WithReference so connection info is injected.
Add a startup configuration check for every connection name the app consumes.
Keep connection names centralized in a constants class to avoid typos.

When it happens

Trigger: Calling AddQdrantClient/AddKeyedQdrantClient with a connection name whose 'ConnectionStrings:{name}' value cannot be parsed into an endpoint (missing key, malformed URI) and no Endpoint configured under 'Aspire:Qdrant:Client' or 'Aspire:Qdrant:Client:{name}'.

Common situations: Running locally without the Aspire AppHost (no connection string injected), appsettings in another environment lacking the ConnectionStrings entry, typo in the connection name, using a plain host:port string where a URI is expected.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/1ee9396ece6068ce. Report an issue: GitHub.

Appendix: source

Thrown at src/Components/Aspire.Qdrant.Client/AspireQdrantExtensions.cs:109

                healthCheckName,
                sp => new QdrantHealthCheck(serviceKey is null ?
                    sp.GetRequiredService<QdrantClient>() :
                    sp.GetRequiredKeyedService<QdrantClient>(serviceKey)),
                failureStatus: null,
                tags: null,
                timeout: settings.HealthCheckTimeout
                ));
        }

        QdrantClient ConfigureQdrant(IServiceProvider serviceProvider)
        {
            if (settings.Endpoint is not null)
            {
                return new QdrantClient(settings.Endpoint, apiKey: settings.Key, loggerFactory: serviceProvider.GetRequiredService<ILoggerFactory>());
            }
            else
            {
                throw new InvalidOperationException(
                        $"A QdrantClient could not be configured. Ensure valid connection information was provided in 'ConnectionStrings:{connectionName}' or either " +
                        $"{nameof(settings.Endpoint)} must be provided " +
                        $"in the '{DefaultConfigSectionName}' or '{DefaultConfigSectionName}:{connectionName}' configuration section.");
            }
        }
    }
}

View on GitHub (pinned to 25830f84bd)