{"record":{"id":"fa96f353155a7af7","repo":"microsoft/aspire","slug":"named-service-references-are-only-supported-for-resources","errorCode":null,"errorMessage":"Named service references are only supported for resources with service discovery.","messagePattern":"Named service references are only supported for resources with service discovery\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting/ResourceBuilderExtensions.cs","lineNumber":977,"sourceCode":"        {\n            return customDispatch;\n        }\n\n        var connectionStringSource = source as IResourceBuilder<IResourceWithConnectionString>;\n        var serviceDiscoverySource = source as IResourceBuilder<IResourceWithServiceDiscovery>;\n        var externalServiceSource = source as IResourceBuilder<ExternalServiceResource>;\n        var hasConnectionString = source.Resource is IResourceWithConnectionString && connectionStringSource is not null;\n        var hasServiceDiscovery = source.Resource is IResourceWithServiceDiscovery && serviceDiscoverySource is not null;\n        var hasExternalService = source.Resource is ExternalServiceResource && externalServiceSource is not null;\n\n        if (hasExternalService && (connectionName is not null || name is not null))\n        {\n            throw new InvalidOperationException(\"Reference names are not supported for external services.\");\n        }\n\n        if (name is not null && !hasServiceDiscovery)\n        {\n            throw new InvalidOperationException(\"Named service references are only supported for resources with service discovery.\");\n        }\n\n        if (connectionName is not null && name is not null && !hasConnectionString)\n        {\n            throw new InvalidOperationException(\"Specify either connectionName or name for service discovery references, but not both.\");\n        }\n\n        if (optional && !hasConnectionString)\n        {\n            throw new InvalidOperationException(\"Optional references are only supported for connection string resources.\");\n        }\n\n        var appliedReference = false;\n\n        if (hasConnectionString)\n        {\n            builder = WithReference(builder, connectionStringSource!, connectionName, optional);\n            appliedReference = true;","sourceCodeStart":959,"sourceCodeEnd":995,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L959-L995","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove the name argument and use the plain reference overload: WithReference(builder, resource).","Add an endpoint (WithEndpoint/WithHttpEndpoint) or service discovery support to the source resource before referencing it by name.","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.","If the source is an external URI, use WithReference(builder, name, uri) with an absolute URI instead of a resource reference."],"exampleFix":"// before\nbuilder.AddProject<Projects.Api>(\"api\")\n       .WithReference(redis, \"cache\"); // redis has no service discovery\n\n// after\nbuilder.AddProject<Projects.Api>(\"api\")\n       .WithReference(redis); // connection-string style reference, no name","handlingStrategy":"validation","validationCode":"static bool SupportsNamedServiceReference(IResource r) =>\n    r is IResourceWithServiceDiscovery || r.Annotations.OfType<EndpointAnnotation>().Any() ||\n    r.Annotations.Any(a => a is ServiceDiscoveryAnnotation);\n// call before WithReference(builder, resource, name): if (!SupportsNamedServiceReference(resource.Resource)) throw/adjust;","typeGuard":"var withSd = resource as IResourceWithServiceDiscovery;\nif (withSd is null) { /* fall back to parameterless WithReference */ }","tryCatchPattern":"try { b = b.WithReference(dep, name); }\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"Named service references\"))\n{ b = b.WithReference(dep); }","preventionTips":["Only pass a name when the source resource has endpoints or service discovery support.","Use the plain WithReference(builder, resource) overload for connection-string resources.","Check the WithReference overload docs before adding a name argument.","Add a unit test around your AppHost resource wiring."],"tags":["aspire","service-discovery","withreference"],"backgroundTag":"unsupported-operation","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"}