{"record":{"id":"6ea6ca7736a445c9","repo":"microsoft/aspire","slug":"clustering-has-not-been-configured-for-this-service","errorCode":null,"errorMessage":"Clustering has not been configured for this service.","messagePattern":"Clustering has not been configured for this service\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.Orleans/OrleansServiceExtensions.cs","lineNumber":437,"sourceCode":"        return builder.WithOrleansReference(orleansService, isSilo: true);\n    }\n\n    internal static IResourceBuilder<T> WithOrleansReference<T>(\n        this IResourceBuilder<T> builder,\n        OrleansService orleansService,\n        bool isSilo)\n        where T : IResourceWithEnvironment, IResourceWithEndpoints\n    {\n        var res = orleansService;\n\n        // Configure clustering\n        if (res.Clustering is { } clustering)\n        {\n            clustering.ConfigureResource(builder, \"Clustering\");\n        }\n        else\n        {\n            throw new InvalidOperationException(\"Clustering has not been configured for this service.\");\n        }\n\n        foreach (var (name, provider) in res.Streaming)\n        {\n            provider.ConfigureResource(builder, $\"Streaming__{name}\");\n        }\n\n        foreach (var (name, provider) in res.BroadcastChannel)\n        {\n            provider.ConfigureResource(builder, $\"BroadcastChannel__{name}\");\n        }\n\n        builder.WithEnvironment(context =>\n        {\n            context.EnvironmentVariables[\"Orleans__ClusterId\"] = res.ClusterId;\n            context.EnvironmentVariables[\"Orleans__ServiceId\"] = res.ServiceId;\n\n            // Enable distributed tracing by default","sourceCodeStart":419,"sourceCodeEnd":455,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.Orleans/OrleansServiceExtensions.cs#L419-L455","documentation":"WithOrleansReference configures the target project's Orleans providers from the referenced service's model. Clustering must have been configured on the source IOrleansService (e.g. via WithClustering); if res.Clustering is null the method throws InvalidOperationException because it cannot emit Clustering configuration for the client. Silently omitting clustering would leave the client unable to join the silo cluster.","triggerScenarios":"Calling projectB.AddProject(...).WithReference(orleansService) (WithOrleansReference) where the IOrleansService was declared without WithClustering.","commonSituations":"Building an Orleans client project and forgetting WithClustering on the server/service declaration; moving clustering configuration to another service during refactor.","solutions":["Add WithClustering(...) to the Orleans service declaration before referencing it: var orleans = builder.AddOrleans(\"my-app\").WithClustering(gravestone);","Ensure the project you reference is the service that declares clustering, not a client-only resource.","If clustering is intentionally unneeded, use a reference mechanism that does not require it (or remove WithReference of the Orleans service)."],"exampleFix":"// before\nvar orleans = builder.AddOrleans(\"orleans\");\nsilo.WithReference(orleans);\n// after\nvar orleans = builder.AddOrleans(\"orleans\").WithClustering(clusteringTable);\nsilo.WithReference(orleans);","handlingStrategy":"validation","validationCode":"// Before WithReference, assert clustering exists\nif (orleansService.Clustering is null)\n{\n    throw new InvalidOperationException(\"Call .WithClustering(...) on the Orleans service before referencing it.\");\n}","typeGuard":null,"tryCatchPattern":"try { project.WithReference(orleansService); } catch (InvalidOperationException ex) when (ex.Message.Contains(\"Clustering has not been configured\")) { /* add WithClustering and retry */ }","preventionTips":["Always pair AddOrleans with WithClustering when clients will reference it","Keep a shared helper that builds the Orleans service with clustering and storage","Reference the service declaration, not a client-only resource"],"tags":["aspire","orleans","clustering","configuration"],"backgroundTag":"missing-required-config","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T09:17:21.228Z"}