microsoft/aspire · error · DistributedApplicationException

The connection string for the resource

Error message

The connection string for the resource '{Resource.Name}' is not available.

What it means

Aspire throws this DistributedApplicationException when code reads a ConnectionStringReference.Value but the referenced resource's connection string has not been generated yet (or never will be). Connection strings are produced asynchronously during resource provisioning/startup, so reading .Value before the resource has emitted one fails. This is the public accessor's guard in ConnectionStringReference.cs:41.

Solutions

Wait for the resource to be running/started before reading the connection string (e.g. use WaitUntil.Running in WaitFor or a ResourceReady/AfterResourceStarted event).
Use the WaitFor completion callbacks (AfterEndpointStarted/ResourceReadyEvent) to access value, where the connection string is guaranteed materialized.
Check the resource actually sets a connection string (ReferenceRelationship to a database/server resource that produces one); if it's a plain container, configure endpoints or an explicit connection string.
If you only need the value lazily, read it inside code executed after startup rather than eagerly at model build time.

Example fix

// before
var cs = builder.CreateResourceBuilder(new MyDbResource("db")).Resource.GetConnectionString(); // throws: not started yet

// after
var db = builder.AddPostgres("pg").AddDatabase("db");
var api = builder.AddProject<Projects.Api>("api")
    .WaitFor(db); // api's code reads the connection string only after db is running

Defensive patterns

Strategy: validation

Validate before calling

// Only read the connection string after the resource has started
if (app.Resource is { } res)
{
    var cs = await app.Resource.GetConnectionStringAsync(cancellationToken); // await availability instead of .Value
}
// or gate reads behind WaitFor(db) with WaitUntil.Running

Type guard

var value = reference.HasContent ? reference.Value : null; // or check resource state == Running before reading

Try / catch

try { var cs = reference.Value; }
catch (DistributedApplicationException ex) { logger.LogWarning(ex, "Connection string not yet available for {Resource}", resource.Name); }

Prevention

Always use WaitFor(target, WaitUntil.Running) before consuming a target's connection string.
Read connection strings in AfterResourceStarted/ResourceReady callbacks, not in model-build or publish-time code.
Confirm the referenced resource type actually emits a connection string (server/database resources do; bare containers may not).

When it happens

Trigger: Accessing ConnectionStringReference.Value before the target resource's connection string is available; reading it in a callback/event that runs before the resource starts; the resource type never publishes a connection string (e.g. a resource without a connection-string contribution such as a container with no endpoint-derived or explicit connection string).

Common situations: Developers grab resource.GetConnectionString() / a ConnectionStringReference in BeforeResourceStarted events, in Publish mode where runtime connection strings don't exist, or reference a container/resource that has no connection string configured.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/ApplicationModel/ConnectionStringReference.cs:41

    ValueTask<string?> IValueProvider.GetValueAsync(CancellationToken cancellationToken)
    {
        return Resource.GetValueAsync(cancellationToken);
    }

    async ValueTask<string?> IValueProvider.GetValueAsync(ValueProviderContext context, CancellationToken cancellationToken)
    {
        var value = await Resource.GetValueAsync(context, cancellationToken).ConfigureAwait(false);

        if (string.IsNullOrEmpty(value) && !Optional)
        {
            ThrowConnectionStringUnavailableException();
        }

        return value;
    }

    internal void ThrowConnectionStringUnavailableException() => throw new DistributedApplicationException($"The connection string for the resource '{Resource.Name}' is not available.");

}

View on GitHub (pinned to 25830f84bd)