{"record":{"id":"762fb10565c0eb11","repo":"microsoft/aspire","slug":"the-connection-string-for-the-resource","errorCode":null,"errorMessage":"The connection string for the resource '{connectionStringReference.Resource.Name}' is not available.","messagePattern":"The connection string for the resource '(.+?)' is not available\\.","errorType":"exception","errorClass":"DistributedApplicationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.Foundry/HostedAgent/AzureHostedAgentResource.cs","lineNumber":403,"sourceCode":"        IResource resource,\n        string environmentVariableName,\n        CancellationToken cancellationToken)\n    {\n        if (context.IsPublishMode)\n        {\n            switch (provider)\n            {\n                case EndpointReference endpointReference:\n                    return await ResolvePublishedEndpointAsync(endpointReference.Property(EndpointProperty.Url), context, hostedAgent, resource, environmentVariableName, cancellationToken).ConfigureAwait(false);\n                case EndpointReferenceExpression endpointReferenceExpression:\n                    return await ResolvePublishedEndpointAsync(endpointReferenceExpression, context, hostedAgent, resource, environmentVariableName, cancellationToken).ConfigureAwait(false);\n                case ReferenceExpression referenceExpression:\n                    return await ResolveReferenceExpressionAsync(referenceExpression, context, hostedAgent, resource, environmentVariableName, cancellationToken).ConfigureAwait(false);\n                case ConnectionStringReference connectionStringReference:\n                    var connectionString = await ResolveReferenceExpressionAsync(connectionStringReference.Resource.ConnectionStringExpression, context, hostedAgent, resource, environmentVariableName, cancellationToken).ConfigureAwait(false);\n                    if (string.IsNullOrEmpty(connectionString) && !connectionStringReference.Optional)\n                    {\n                        throw new DistributedApplicationException($\"The connection string for the resource '{connectionStringReference.Resource.Name}' is not available.\");\n                    }\n\n                    return connectionString;\n                case IResourceWithConnectionString connectionStringResource and not ParameterResource:\n                    return await ResolveReferenceExpressionAsync(connectionStringResource.ConnectionStringExpression, context, hostedAgent, resource, environmentVariableName, cancellationToken).ConfigureAwait(false);\n            }\n        }\n\n        return await provider.GetValueAsync(\n            new ValueProviderContext\n            {\n                ExecutionContext = context,\n                Caller = resource\n            },\n            cancellationToken).ConfigureAwait(false);\n    }\n\n    private static async ValueTask<string?> ResolveReferenceExpressionAsync(","sourceCodeStart":385,"sourceCodeEnd":421,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.Foundry/HostedAgent/AzureHostedAgentResource.cs#L385-L421","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nbuilder.AddHostedAgent(\"agent\").WithReference(db) // db connection string unset, non-optional\n// after\nbuilder.AddHostedAgent(\"agent\").WithReference(db, optional: true)\n// or: assign db's connection string parameter\nvar db = builder.AddConnectionString(\"db\", \"ConnectionStrings__db\");","handlingStrategy":"validation","validationCode":"foreach (var reference in references)\n{\n    var cs = await reference.Resource.ConnectionStringExpression.GetValueAsync(ct);\n    if (!reference.Optional && string.IsNullOrEmpty(cs))\n        throw new InvalidOperationException($\"Missing required connection string for '{reference.Resource.Name}'.\");\n}","typeGuard":null,"tryCatchPattern":"try\n{\n    var envVars = await hostedAgentResource.GetResolvedEnvironmentVariablesAsync(...);\n}\ncatch (DistributedApplicationException ex) when (ex.Message.Contains(\"is not available\"))\n{\n    logger.LogError(ex, \"A required dependency connection string could not be resolved.\");\n    throw;\n}","preventionTips":["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"],"tags":["azure","foundry","connection-string","distributed-application"],"backgroundTag":"missing-config-value","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"}