microsoft/aspire · error · InvalidOperationException

Reference names are not supported for external services.

Error message

Reference names are not supported for external services.

What it means

ExternalServiceResource instances (references to services outside the app model, e.g. an external HTTP API) are referenced in only one form: bare, with service discovery under the resource's own name. Aspire rejects supplying connectionName or name when the referenced resource is an ExternalServiceResource, because external services have no connection string and their discovery name is fixed, so a custom reference name is meaningless.

Solutions

Remove name and connectionName: builder.WithReference(externalService) references it under its own resource name.
If you want a different discovery key, rename the external service resource at creation time (AddExternalService("desired-name", url)).
If you need both a connection string and a name, reference a resource that implements IResourceWithConnectionString instead of an ExternalServiceResource.
For custom env-var naming, inject manually with WithEnvironment.

Example fix

// before
builder.WithReference(externalApi, name: "api");

// after
builder.WithReference(externalApi); // or rename at creation: builder.AddExternalService("api", url)

Defensive patterns

Strategy: validation

Validate before calling

if (source.Resource is ExternalServiceResource && (connectionName is not null || name is not null))
{
    throw new ArgumentException("External service references must not specify connectionName or name.");
}

Type guard

bool allowsReferenceName(object source) => source is IResourceBuilder<IResource> { Resource: IResourceWithServiceDiscovery } and not IResourceBuilder<ExternalServiceResource>;

Prevention

Reference ExternalServiceResource values bare, without name/connectionName.
Set the desired discovery key when creating the external service via AddExternalService("name", ...).
Only pass name for resources implementing IResourceWithServiceDiscovery that are not external services.

When it happens

Trigger: builder.WithReference(externalServiceBuilder, name: "api") or builder.WithReference(externalServiceBuilder, connectionName: "external") where externalServiceBuilder.Resource is ExternalServiceResource and the corresponding source builder exists — guard at src/Aspire.Hosting/ResourceBuilderExtensions.cs:970-973.

Common situations: Trying to alias an external service under a friendlier discovery name; copy-pasting a named-reference call from a database/resource reference; adding connectionName to force connection-string semantics on an external URL resource.

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/8b619ac18f1f1fcc. Report an issue: GitHub.

Appendix: source

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

        bool optional,
        string? name)
        where TDestination : IResourceWithEnvironment
    {
        if (TryDispatchCustomWithReference(builder, source, connectionName, optional, name, out var customDispatch))
        {
            return customDispatch;
        }

        var connectionStringSource = source as IResourceBuilder<IResourceWithConnectionString>;
        var serviceDiscoverySource = source as IResourceBuilder<IResourceWithServiceDiscovery>;
        var externalServiceSource = source as IResourceBuilder<ExternalServiceResource>;
        var hasConnectionString = source.Resource is IResourceWithConnectionString && connectionStringSource is not null;
        var hasServiceDiscovery = source.Resource is IResourceWithServiceDiscovery && serviceDiscoverySource is not null;
        var hasExternalService = source.Resource is ExternalServiceResource && externalServiceSource is not null;

        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;

View on GitHub (pinned to 25830f84bd)