microsoft/aspire · error · InvalidOperationException

Endpoint references do not support connectionName…

Error message

Endpoint references do not support connectionName, optional, or name options.

What it means

Aspire's WithReference dispatcher accepts resource builders, EndpointReference, string URIs, or Uri instances, but endpoint references only work in their bare form. EndpointReference values model a direct endpoint binding (host/port injected via service discovery), so options like connectionName, optional, or name have no meaning for them. When an EndpointReference is passed together with any of those options, the dispatcher throws this InvalidOperationException instead of silently ignoring the options.

Solutions

Remove the connectionName, optional, and name arguments and call builder.WithReference(endpointReference) with only the endpoint reference.
If you need a custom service name or optional semantics, reference the resource builder instead: builder.WithReference(resourceBuilder, name: "...", optional: true) (name requires the source to implement IResourceWithServiceDiscovery; optional requires a connection string resource).
If you need the endpoint under a different key, inject the environment variable manually via WithEnvironment using endpointReference.Property(EndpointProperty.HostAndPort).

Example fix

// before
builder.WithReference(frontend.GetEndpoint("https"), optional: true);

// after
builder.WithReference(frontend.GetEndpoint("https"));

Defensive patterns

Strategy: validation

Validate before calling

if (source is EndpointReference && (connectionName is not null || optional || name is not null))
{
    throw new ArgumentException("Endpoint references cannot be combined with connectionName, optional, or name.");
}

Type guard

bool isBareEndpointReference(object source, string? connectionName, bool optional, string? name) => source is EndpointReference && connectionName is null && !optional && name is null;

Prevention

Call endpoint references bare: WithReference(endpoint) with no extra arguments.
Remember optional/connectionName apply only to connection-string resources, name only to service-discovery resources.
Check the source value's type before choosing which optional arguments to pass.

When it happens

Trigger: Calling builder.WithReference(endpointReference, connectionName: "db"), .WithReference(endpointReference, optional: true), or .WithReference(endpointReference, name: "my-service") — i.e. passing an EndpointReference while any of connectionName != null, optional == true, or name != null. The matching switch arm is src/Aspire.Hosting/ResourceBuilderExtensions.cs:926.

Common situations: Copying a call pattern from a connection-string resource reference (which supports connectionName/optional) and reusing it for an endpoint reference; trying to mark an endpoint reference as optional because the endpoint may not be running; attempting to alias an endpoint reference under a friendly service name.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

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

    /// Adds a reference to another resource
    /// </summary>
    [AspireExport]
    internal static IResourceBuilder<TDestination> WithReference<TDestination>(
        this IResourceBuilder<TDestination> builder,
        [AspireUnion(typeof(IResourceBuilder<IResource>), typeof(EndpointReference), typeof(string), typeof(Uri))] object source,
        string? connectionName = null,
        bool optional = false,
        string? name = null)
        where TDestination : IResourceWithEnvironment
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentNullException.ThrowIfNull(source);

        return source switch
        {
            IResourceBuilder<IResource> resourceBuilder => WithReferenceResource(builder, resourceBuilder, connectionName, optional, name),
            EndpointReference endpointReference when connectionName is null && !optional && name is null => builder.WithReference(endpointReference),
            EndpointReference => throw new InvalidOperationException("Endpoint references do not support connectionName, optional, or name options."),
            Uri uri when connectionName is null && !optional && name is not null => builder.WithReference(name, uri),
            Uri => throw new InvalidOperationException("URI references require the name option and do not support connectionName or optional."),
            string uriString when connectionName is null && !optional && name is not null => builder.WithReference(name, CreateUri(uriString)),
            string => throw new InvalidOperationException("URI references require the name option and do not support connectionName or optional."),
            _ => throw new ArgumentException("Source must be a resource builder, endpoint reference, or URI string.", nameof(source))
        };
    }

    // Preserve the historical dispatcher signature for internal reflection-based tests.
    internal static IResourceBuilder<TDestination> WithReference<TDestination>(
        this IResourceBuilder<TDestination> builder,
        IResourceBuilder<IResource> source,
        string? connectionName = null,
        bool optional = false,
        string? name = null)
        where TDestination : IResourceWithEnvironment
    {
        ArgumentNullException.ThrowIfNull(builder);

View on GitHub (pinned to 25830f84bd)