microsoft/aspire · error · DistributedApplicationException

The connection string for the resource

Error message

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

What it means

When resolving environment variables for a hosted agent, a ConnectionStringReference whose connection string resolves to null/empty and is not marked Optional causes this DistributedApplicationException. It guards agents from being deployed with a required dependency connection string silently missing.

Solutions

Set a value for the referenced resource's connection string (assign the parameter or complete provisioning of the referenced resource)
Mark the connection string reference optional with .WithReference(..., optional: true) if the dependency is genuinely optional
Check that the referenced resource actually produces a connection string (IResourceWithConnectionString)
Inspect GetResolvedEnvironmentVariablesAsync input configuration for a misspelled resource name

Example fix

// before
builder.AddHostedAgent("agent").WithReference(db) // db connection string unset, non-optional
// after
builder.AddHostedAgent("agent").WithReference(db, optional: true)
// or: assign db's connection string parameter
var db = builder.AddConnectionString("db", "ConnectionStrings__db");

Defensive patterns

Strategy: validation

Validate before calling

foreach (var reference in references)
{
    var cs = await reference.Resource.ConnectionStringExpression.GetValueAsync(ct);
    if (!reference.Optional && string.IsNullOrEmpty(cs))
        throw new InvalidOperationException($"Missing required connection string for '{reference.Resource.Name}'.");
}

Try / catch

try
{
    var envVars = await hostedAgentResource.GetResolvedEnvironmentVariablesAsync(...);
}
catch (DistributedApplicationException ex) when (ex.Message.Contains("is not available"))
{
    logger.LogError(ex, "A required dependency connection string could not be resolved.");
    throw;
}

Prevention

Set values for all referenced resources' connection string parameters before deployment
Use optional: true only when the dependency is genuinely optional
Verify referenced resources implement IResourceWithConnectionString
Keep resource names consistent to avoid resolving the wrong reference

When it happens

Trigger: A hosted agent references another resource's connection string (e.g. via WithReference), and that resource's ConnectionStringExpression evaluates to null or empty at resolution time while the reference was declared non-optional.

Common situations: Referenced resource (database, cache, service) has not been provisioned or its connection string parameter has no value; the parameter resource backing the connection string is unset in the current environment; typos in the resource name produce a reference that never resolves.

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/762fb10565c0eb11. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.Foundry/HostedAgent/AzureHostedAgentResource.cs:403

        IResource resource,
        string environmentVariableName,
        CancellationToken cancellationToken)
    {
        if (context.IsPublishMode)
        {
            switch (provider)
            {
                case EndpointReference endpointReference:
                    return await ResolvePublishedEndpointAsync(endpointReference.Property(EndpointProperty.Url), context, hostedAgent, resource, environmentVariableName, cancellationToken).ConfigureAwait(false);
                case EndpointReferenceExpression endpointReferenceExpression:
                    return await ResolvePublishedEndpointAsync(endpointReferenceExpression, context, hostedAgent, resource, environmentVariableName, cancellationToken).ConfigureAwait(false);
                case ReferenceExpression referenceExpression:
                    return await ResolveReferenceExpressionAsync(referenceExpression, context, hostedAgent, resource, environmentVariableName, cancellationToken).ConfigureAwait(false);
                case ConnectionStringReference connectionStringReference:
                    var connectionString = await ResolveReferenceExpressionAsync(connectionStringReference.Resource.ConnectionStringExpression, context, hostedAgent, resource, environmentVariableName, cancellationToken).ConfigureAwait(false);
                    if (string.IsNullOrEmpty(connectionString) && !connectionStringReference.Optional)
                    {
                        throw new DistributedApplicationException($"The connection string for the resource '{connectionStringReference.Resource.Name}' is not available.");
                    }

                    return connectionString;
                case IResourceWithConnectionString connectionStringResource and not ParameterResource:
                    return await ResolveReferenceExpressionAsync(connectionStringResource.ConnectionStringExpression, context, hostedAgent, resource, environmentVariableName, cancellationToken).ConfigureAwait(false);
            }
        }

        return await provider.GetValueAsync(
            new ValueProviderContext
            {
                ExecutionContext = context,
                Caller = resource
            },
            cancellationToken).ConfigureAwait(false);
    }

    private static async ValueTask<string?> ResolveReferenceExpressionAsync(

View on GitHub (pinned to 25830f84bd)