{"record":{"id":"4c246f3a9546e4ce","repo":"microsoft/aspire","slug":"a-cosmosclient-could-not-be-configured-ensure-valid","errorCode":null,"errorMessage":"A CosmosClient could not be configured. Ensure valid connection information was provided in 'ConnectionStrings:{connectionName}' or either {nameof(settings.ConnectionString)} or {nameof(settings.AccountEndpoint)} must be provided in the '{DefaultConfigSectionName}' or '{DefaultConfigSectionName}:{connectionName}' configuration section.","messagePattern":"A CosmosClient could not be configured\\. Ensure valid connection information was provided in 'ConnectionStrings:(.+?)' or either (.+?) or (.+?) must be provided in the '(.+?)' or '(.+?):(.+?)' configuration section\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Components/Aspire.Microsoft.Azure.Cosmos/AspireMicrosoftAzureCosmosExtensions.cs","lineNumber":302,"sourceCode":"        clientOptions.ApplicationName = cosmosApplicationName;\n\n        return clientOptions;\n    }\n\n    internal static CosmosClient GetCosmosClient(string connectionName, MicrosoftAzureCosmosSettings settings, CosmosClientOptions clientOptions)\n    {\n        if (!string.IsNullOrEmpty(settings.ConnectionString))\n        {\n            return new CosmosClient(settings.ConnectionString, clientOptions);\n        }\n        else if (settings.AccountEndpoint is not null)\n        {\n            var credential = settings.Credential ?? AzureCredentialHelper.CreateDefaultAzureCredential();\n            return new CosmosClient(settings.AccountEndpoint.OriginalString, credential, clientOptions);\n        }\n        else\n        {\n            throw new InvalidOperationException(\n                    $\"A CosmosClient could not be configured. Ensure valid connection information was provided in 'ConnectionStrings:{connectionName}' or either \" +\n                    $\"{nameof(settings.ConnectionString)} or {nameof(settings.AccountEndpoint)} must be provided \" +\n                    $\"in the '{DefaultConfigSectionName}' or '{DefaultConfigSectionName}:{connectionName}' configuration section.\");\n        }\n    }\n}\n","sourceCodeStart":284,"sourceCodeEnd":309,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Components/Aspire.Microsoft.Azure.Cosmos/AspireMicrosoftAzureCosmosExtensions.cs#L284-L309","documentation":"GetCosmosClient builds a CosmosClient from either a connection string or an account endpoint plus credential. When neither settings.ConnectionString nor settings.AccountEndpoint resolved (from ConnectionStrings or the Aspire:Microsoft:Azure:Cosmos config sections), Aspire throws because no client can authenticate or address the account.","triggerScenarios":"Calling AddAzureCosmosClient/AddKeyedAzureCosmosClient (or any API that lazily builds the client, like AddAzureCosmosDatabase/Container) where ConnectionStrings:{connectionName} is missing and no AccountEndpoint/ConnectionString is set in the 'Aspire:Microsoft:Azure:Cosmos' or 'Aspire:Microsoft:Azure:Cosmos:{connectionName}' sections.","commonSituations":"Running without the AppHost-injected connection string; connection name typo; AccountEndpoint configured without credentials being resolvable (different failure) versus endpoint entirely absent (this error); section name changed across package versions.","solutions":["Add ConnectionStrings:{connectionName} with the Cosmos account connection string or account endpoint URI.","Ensure the project references the Cosmos DB hosting resource and uses WithReference in the AppHost so the connection is injected.","Set 'ConnectionString' or 'AccountEndpoint' in the 'Aspire:Microsoft:Azure:Cosmos' (or per-connection) config section.","Verify config section names: DefaultConfigSectionName is 'Aspire:Microsoft:Azure:Cosmos'."],"exampleFix":"// before\nbuilder.AddAzureCosmosClient(\"cosmos\"); // nothing configured\n// after\n// appsettings.json: \"ConnectionStrings\": { \"cosmos\": \"AccountEndpoint=https://myacct.documents.azure.com/;AccountKey=...\" }\nbuilder.AddAzureCosmosClient(\"cosmos\");","handlingStrategy":"validation","validationCode":"var cs = builder.Configuration.GetConnectionString(\"cosmos\");\nvar section = builder.Configuration.GetSection(\"Aspire:Microsoft:Azure:Cosmos\");\nif (string.IsNullOrEmpty(cs) && section[\"ConnectionString\"] is null && section[\"AccountEndpoint\"] is null)\n    throw new InvalidOperationException(\"Configure ConnectionStrings:cosmos or Aspire:Microsoft:Azure:Cosmos (ConnectionString/AccountEndpoint) before resolving CosmosClient.\");","typeGuard":null,"tryCatchPattern":"try { client.ReadAccountAsync().GetAwaiter().GetResult(); }\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"A CosmosClient could not be configured\"))\n{\n    logger.LogError(ex, \"Cosmos connection info missing for 'cosmos'.\");\n    throw;\n}","preventionTips":["Register the Cosmos DB resource in the AppHost and WithReference the project.","Keep the connection name argument consistent across AppHost and client registration.","Remember client-level settings apply to Database/Container registrations too, since they lazily build the same client."],"tags":["azure","cosmos","configuration","connection-string"],"backgroundTag":"missing-required-config","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}