microsoft/aspire · error · DistributedApplicationException

ConnectionStringAvailableEvent was published for the

Error message

ConnectionStringAvailableEvent was published for the '{builder.Resource.Name}' resource but the connection string was null.

What it means

RunAsEmulator subscribes to ConnectionStringAvailableEvent and expects the resource's ConnectionStringExpression to yield a non-null connection string by that point. If the event fires but GetValueAsync returns null, the internal lifecycle contract is broken and a DistributedApplicationException is thrown, because the emulator's CosmosClient cannot be created.

Solutions

Create the resource via AddAzureCosmosDB(...).RunAsEmulator() without custom mutations to ConnectionStringExpression.
Check custom event handlers or annotations that interfere with connection string resolution.
Verify the resource named in the error message is the one actually configured as the emulator.

Example fix

// before
var cosmos = builder.AddAzureCosmosDB("cosmos");
cosmos.Resource.ConnectionStringExpression = customExpression; // resolves to null in run mode
cosmos.RunAsEmulator();
// after
var cosmos = builder.AddAzureCosmosDB("cosmos").RunAsEmulator(); // default expression resolves the emulator connection string

Defensive patterns

Strategy: try-catch

Try / catch

try { await builder.AddAzureCosmosDB("cosmos").RunAsEmulatorAsync(); } catch (DistributedApplicationException ex) when (ex.Message.Contains("connection string was null")) { /* inspect resource model / expression overrides */ }

Prevention

Do not override ConnectionStringExpression on emulator resources.
Avoid custom model mutations after RunAsEmulator.
Use the standard AddAzureCosmosDB fluent chain end to end.

When it happens

Trigger: Running a Cosmos DB resource as an emulator when the connection string expression fails to resolve, e.g. the resource model was mutated after AddAzureCosmosDB so no connection string endpoint is set, or the expression was replaced with one that returns null in run mode.

Common situations: Custom transformations or publish-mode mutations that strip the connection string; replacing ConnectionStringExpression with a custom reference that has no value in run mode; modifying resource annotations that the expression depends on.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Azure.CosmosDB/AzureCosmosDBExtensions.cs:126

        builder.WithAnnotation(new EmulatorResourceAnnotation());

        var scheme = useVNext ? "http" : null;
        builder.WithEndpoint(name: "emulator", scheme: scheme, targetPort: 8081)
               .WithAnnotation(new ContainerImageAnnotation
               {
                   Registry = CosmosDBEmulatorContainerImageTags.Registry,
                   Image = CosmosDBEmulatorContainerImageTags.Image,
                   Tag = useVNext ? CosmosDBEmulatorContainerImageTags.Tag : CosmosDBEmulatorContainerImageTags.ClassicTag
               });

        CosmosClient? cosmosClient = null;
        builder.OnConnectionStringAvailable(async (cosmosDb, @event, ct) =>
        {
            var connectionString = await cosmosDb.ConnectionStringExpression.GetValueAsync(ct).ConfigureAwait(false);

            if (connectionString == null)
            {
                throw new DistributedApplicationException($"ConnectionStringAvailableEvent was published for the '{builder.Resource.Name}' resource but the connection string was null.");
            }

            cosmosClient = CreateCosmosClient(connectionString);
        })
        .OnResourceReady(async (cosmosDb, @event, ct) =>
        {
            if (cosmosClient is null)
            {
                throw new InvalidOperationException("CosmosClient is not initialized.");
            }

            await cosmosClient.ReadAccountAsync().WaitAsync(ct).ConfigureAwait(false);

            foreach (var database in cosmosDb.Databases)
            {
                var db = (await cosmosClient.CreateDatabaseIfNotExistsAsync(database.DatabaseName, cancellationToken: ct).ConfigureAwait(false)).Database;

                foreach (var container in database.Containers)

View on GitHub (pinned to 25830f84bd)