microsoft/aspire · error · InvalidOperationException

Optional references are only supported for connection…

Error message

Optional references are only supported for connection string resources.

What it means

The optional flag on WithReference marks a reference as one the consuming resource can start without (e.g. skip validation when the dependency is missing). Aspire only implements optional semantics for resources that expose a connection string; there is no optional-mode story for endpoint/service-discovery references, so combining optional=true with a non-connection-string reference throws.

Solutions

Remove the optional flag when the reference is endpoint/service-discovery based.
If optionality is required, model the dependency as a connection string resource (or use a parameter) so optional is supported.
Handle absence at the consuming app level (retry/fallback) rather than via optional reference semantics.
Keep optional: true only on WithReference calls against resources implementing IResourceWithConnectionString.

Example fix

// before
builder.AddProject<Projects.Frontend>("frontend")
       .WithReference(api, optional: true); // endpoint-based reference

// after
builder.AddProject<Projects.Frontend>("frontend")
       .WithReference(api);

Defensive patterns

Strategy: validation

Validate before calling

static bool IsConnectionStringResource(IResource r) => r is IResourceWithConnectionString;
// only pass optional: true when IsConnectionStringResource(dep.Resource);

Type guard

if (dep is not IResourceWithConnectionString) { /* do not pass optional: true */ }

Try / catch

try { b = b.WithReference(dep, optional: true); }
catch (InvalidOperationException ex) when (ex.Message.Contains("Optional references"))
{ b = b.WithReference(dep); }

Prevention

Use optional only for connection-string references (databases, caches).
Model optional service dependencies at the application level instead.
Re-read overload signatures when copying WithReference patterns between resources.

When it happens

Trigger: Calling WithReference(builder, reference, name, optional: true) where the source resource has no connection string — e.g. a project or container resource referenced via endpoints, or an external service reference.

Common situations: Trying to make an endpoint reference to another project 'optional' so the app runs without it; passing optional: true out of habit from connection-string references; copying an optional DB reference pattern onto a service reference.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/ResourceBuilderExtensions.cs:987

        if (hasExternalService && (connectionName is not null || name is not null))
        {
            throw new InvalidOperationException("Reference names are not supported for external services.");
        }

        if (name is not null && !hasServiceDiscovery)
        {
            throw new InvalidOperationException("Named service references are only supported for resources with service discovery.");
        }

        if (connectionName is not null && name is not null && !hasConnectionString)
        {
            throw new InvalidOperationException("Specify either connectionName or name for service discovery references, but not both.");
        }

        if (optional && !hasConnectionString)
        {
            throw new InvalidOperationException("Optional references are only supported for connection string resources.");
        }

        var appliedReference = false;

        if (hasConnectionString)
        {
            builder = WithReference(builder, connectionStringSource!, connectionName, optional);
            appliedReference = true;
        }

        if (hasServiceDiscovery)
        {
            var serviceName = hasConnectionString ? name : name ?? connectionName;
            builder = serviceName is null
                ? WithReference(builder, serviceDiscoverySource!)
                : WithReference(builder, serviceDiscoverySource!, serviceName);
            appliedReference = true;
        }

View on GitHub (pinned to 25830f84bd)