{"record":{"id":"6437154fce46f14e","repo":"microsoft/aspire","slug":"a-database-could-not-be-configured-ensure-valid-connection","errorCode":null,"errorMessage":"A Database could not be configured. Ensure valid connection information was provided in 'ConnectionStrings:{connectionName}'.","messagePattern":"A Database could not be configured\\. Ensure valid connection information was provided in 'ConnectionStrings:(.+?)'\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Components/Aspire.Microsoft.Azure.Cosmos/CosmosDatabaseBuilder.cs","lineNumber":28,"sourceCode":"/// <summary>\n/// Represents a builder that can be used to register multiple container\n/// instances against the same Cosmos database connection.\n/// </summary>\npublic sealed class CosmosDatabaseBuilder(\n    IHostApplicationBuilder hostBuilder,\n    string connectionName,\n    MicrosoftAzureCosmosSettings settings,\n    CosmosClientOptions clientOptions)\n{\n    private CosmosClient? _client;\n\n    internal CosmosDatabaseBuilder AddDatabase()\n    {\n        hostBuilder.Services.AddSingleton(sp =>\n        {\n            if (string.IsNullOrEmpty(settings.DatabaseName))\n            {\n                throw new InvalidOperationException(\n                    $\"A Database could not be configured. Ensure valid connection information was provided in 'ConnectionStrings:{connectionName}'.\");\n            }\n            _client ??= AspireMicrosoftAzureCosmosExtensions.GetCosmosClient(connectionName, settings, clientOptions);\n            return _client.GetDatabase(settings.DatabaseName);\n        });\n\n        return this;\n    }\n\n    internal CosmosDatabaseBuilder AddKeyedDatabase()\n    {\n        hostBuilder.Services.AddKeyedSingleton(connectionName, (sp, _) =>\n        {\n            if (string.IsNullOrEmpty(settings.DatabaseName))\n            {\n                throw new InvalidOperationException(\n                    $\"A Database could not be configured. Ensure valid connection information was provided in 'ConnectionStrings:{connectionName}'.\");\n            }","sourceCodeStart":10,"sourceCodeEnd":46,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Components/Aspire.Microsoft.Azure.Cosmos/CosmosDatabaseBuilder.cs#L10-L46","documentation":"CosmosDatabaseBuilder.AddDatabase lazily creates the Database singleton. It requires settings.DatabaseName to be set; without a database name, GetDatabase cannot be called. The message also hints that the database name usually comes from the connection string for Cosmos in Aspire.","triggerScenarios":"Calling AddAzureCosmosDatabase(connectionName) where the connection string '{connectionName}' does not exist or does not include the database name, and settings.DatabaseName was not set in the 'Aspire:Microsoft:Azure:Cosmos' config section or via configureSettings.","commonSituations":"Connection string points only to the account endpoint without a database path; developer expected AddDatabase to default to a database in config; database name keys in config misspelled; keyed/non-keyed name mismatch.","solutions":["Set DatabaseName in 'Aspire:Microsoft:Azure:Cosmos:{connectionName}' config (or global 'Aspire:Microsoft:Azure:Cosmos' section).","Set it in code: builder.AddAzureCosmosDatabase(\"cosmos\", settings => settings.DatabaseName = \"mydb\");.","Ensure ConnectionStrings:{connectionName} exists and includes the database name when using the connection-string convention.","Also make sure the account connection itself resolves, since AddDatabase lazily builds the CosmosClient too."],"exampleFix":"// before\nbuilder.AddAzureCosmosDatabase(\"cosmos\"); // DatabaseName unset\n// after\n// appsettings.json: \"Aspire:Microsoft:Azure:Cosmos:cosmos\": { \"DatabaseName\": \"orders\" }\nbuilder.AddAzureCosmosDatabase(\"cosmos\");","handlingStrategy":"validation","validationCode":"var dbName = builder.Configuration[\"Aspire:Microsoft:Azure:Cosmos:cosmos:DatabaseName\"];\nif (string.IsNullOrEmpty(dbName))\n    throw new InvalidOperationException(\"DatabaseName must be configured (or present in the connection string) before AddAzureCosmosDatabase.\");","typeGuard":null,"tryCatchPattern":"try { database.GetContainerQueryIterator().ReadNextAsync(); }\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"A Database could not be configured\"))\n{\n    logger.LogError(ex, \"Cosmos database name missing for 'cosmos'.\");\n    throw;\n}","preventionTips":["Always supply DatabaseName via config or configureSettings when calling AddAzureCosmosDatabase.","Verify the connection string format includes the database when relying on it for the name.","Add a startup validation that resolves the Database before the app accepts traffic."],"tags":["azure","cosmos","configuration","database"],"backgroundTag":"missing-required-config-field","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"}