{"record":{"id":"8b619ac18f1f1fcc","repo":"microsoft/aspire","slug":"reference-names-are-not-supported-for-external-services","errorCode":null,"errorMessage":"Reference names are not supported for external services.","messagePattern":"Reference names are not supported for external services\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting/ResourceBuilderExtensions.cs","lineNumber":972,"sourceCode":"        bool optional,\n        string? name)\n        where TDestination : IResourceWithEnvironment\n    {\n        if (TryDispatchCustomWithReference(builder, source, connectionName, optional, name, out var customDispatch))\n        {\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;","sourceCodeStart":954,"sourceCodeEnd":990,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L954-L990","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nbuilder.WithReference(externalApi, name: \"api\");\n\n// after\nbuilder.WithReference(externalApi); // or rename at creation: builder.AddExternalService(\"api\", url)","handlingStrategy":"validation","validationCode":"if (source.Resource is ExternalServiceResource && (connectionName is not null || name is not null))\n{\n    throw new ArgumentException(\"External service references must not specify connectionName or name.\");\n}","typeGuard":"bool allowsReferenceName(object source) => source is IResourceBuilder<IResource> { Resource: IResourceWithServiceDiscovery } and not IResourceBuilder<ExternalServiceResource>;","tryCatchPattern":null,"preventionTips":["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."],"tags":["aspire","withreference","external-service","invalid-argument-combination"],"backgroundTag":"conflicting-config-options","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"}