microsoft/aspire · error · InvalidOperationException

Clustering has not been configured for this service.

Error message

Clustering has not been configured for this service.

What it means

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.

Solutions

  1. Add WithClustering(...) to the Orleans service declaration before referencing it: var orleans = builder.AddOrleans("my-app").WithClustering(gravestone);
  2. Ensure the project you reference is the service that declares clustering, not a client-only resource.
  3. If clustering is intentionally unneeded, use a reference mechanism that does not require it (or remove WithReference of the Orleans service).

Example fix

// before
var orleans = builder.AddOrleans("orleans");
silo.WithReference(orleans);
// after
var orleans = builder.AddOrleans("orleans").WithClustering(clusteringTable);
silo.WithReference(orleans);
Defensive patterns

Strategy: validation

Validate before calling

// Before WithReference, assert clustering exists
if (orleansService.Clustering is null)
{
    throw new InvalidOperationException("Call .WithClustering(...) on the Orleans service before referencing it.");
}

Try / catch

try { project.WithReference(orleansService); } catch (InvalidOperationException ex) when (ex.Message.Contains("Clustering has not been configured")) { /* add WithClustering and retry */ }

Prevention

When it happens

Trigger: Calling projectB.AddProject(...).WithReference(orleansService) (WithOrleansReference) where the IOrleansService was declared without WithClustering.

Common situations: Building an Orleans client project and forgetting WithClustering on the server/service declaration; moving clustering configuration to another service during refactor.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/6ea6ca7736a445c9. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.Orleans/OrleansServiceExtensions.cs:437

        return builder.WithOrleansReference(orleansService, isSilo: true);
    }

    internal static IResourceBuilder<T> WithOrleansReference<T>(
        this IResourceBuilder<T> builder,
        OrleansService orleansService,
        bool isSilo)
        where T : IResourceWithEnvironment, IResourceWithEndpoints
    {
        var res = orleansService;

        // Configure clustering
        if (res.Clustering is { } clustering)
        {
            clustering.ConfigureResource(builder, "Clustering");
        }
        else
        {
            throw new InvalidOperationException("Clustering has not been configured for this service.");
        }

        foreach (var (name, provider) in res.Streaming)
        {
            provider.ConfigureResource(builder, $"Streaming__{name}");
        }

        foreach (var (name, provider) in res.BroadcastChannel)
        {
            provider.ConfigureResource(builder, $"BroadcastChannel__{name}");
        }

        builder.WithEnvironment(context =>
        {
            context.EnvironmentVariables["Orleans__ClusterId"] = res.ClusterId;
            context.EnvironmentVariables["Orleans__ServiceId"] = res.ServiceId;

            // Enable distributed tracing by default

View on GitHub (pinned to 25830f84bd)