microsoft/aspire · error · InvalidOperationException

Named service references are only supported for resources…

Error message

Named service references are only supported for resources with service discovery.

What it means

Aspire's WithReference API lets you bind a named service reference (a logical service name used for service discovery) between resources. The library only supports named references when the source resource advertises service discovery support (via ServiceDiscoveryAnnotation or an endpoint reference). If the resource cannot resolve service names, a named reference would inject environment variables nothing consumes, so the host fails fast.

Solutions

  1. Remove the name argument and use the plain reference overload: WithReference(builder, resource).
  2. Add an endpoint (WithEndpoint/WithHttpEndpoint) or service discovery support to the source resource before referencing it by name.
  3. If you only need the connection string, use WithReference(builder, resource) and access it via the standard connection-string environment variable instead of service discovery.
  4. If the source is an external URI, use WithReference(builder, name, uri) with an absolute URI instead of a resource reference.

Example fix

// before
builder.AddProject<Projects.Api>("api")
       .WithReference(redis, "cache"); // redis has no service discovery

// after
builder.AddProject<Projects.Api>("api")
       .WithReference(redis); // connection-string style reference, no name
Defensive patterns

Strategy: validation

Validate before calling

static bool SupportsNamedServiceReference(IResource r) =>
    r is IResourceWithServiceDiscovery || r.Annotations.OfType<EndpointAnnotation>().Any() ||
    r.Annotations.Any(a => a is ServiceDiscoveryAnnotation);
// call before WithReference(builder, resource, name): if (!SupportsNamedServiceReference(resource.Resource)) throw/adjust;

Type guard

var withSd = resource as IResourceWithServiceDiscovery;
if (withSd is null) { /* fall back to parameterless WithReference */ }

Try / catch

try { b = b.WithReference(dep, name); }
catch (InvalidOperationException ex) when (ex.Message.Contains("Named service references"))
{ b = b.WithReference(dep); }

Prevention

When it happens

Trigger: Calling WithReference<TBuilder>(builder, reference, name) (or WithReference(builder, resource, name)) with a non-null name against a source resource that has no service discovery: it has no endpoints, no ServiceDiscoveryAnnotation, and is not an external service HTTP resource.

Common situations: Passing a name overload (e.g. WithReference(cache, "mycache")) against a resource like a container or custom resource that only provides a connection string or nothing at all; copy-pasting a named-reference call from a project resource example onto a database or parameter resource; upgrading code where the source resource's endpoint configuration was removed.

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

Appendix: source

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

        {
            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;

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

View on GitHub (pinned to 25830f84bd)