microsoft/aspire · error · InvalidOperationException

Resource ' ' uses multiple replicas and a proxy-less…

Error message

Resource '{modelResourceName}' uses multiple replicas and a proxy-less endpoint '{ea.Name}'. These features do not work together.

What it means

Aspire rejects application-model resources that both run multiple replicas (instance count > 1) and expose a proxy-less endpoint (IsProxied = false). With no DCP proxy in front, each replica would need its own port, so the single endpoint cannot be surfaced coherently. The library throws at DCP model-generation time rather than failing confusingly at runtime.

Solutions

  1. Re-enable the proxy on the endpoint: WithEndpoint(name: ..., isProxied: true) so replicas can share one proxied endpoint.
  2. Remove WithReplicas(n) (set replicas to 1) if you specifically need the proxy-less endpoint.
  3. Move to a container resource, which supports proxy-less endpoints with replicas via port mapping semantics, if the proxy-less requirement is architectural.

Example fix

// before
var svc = builder.AddProject<Projects.Worker>("worker")
    .WithEndpoint("http", e => e.IsProxied = false)
    .WithReplicas(3);
// after
var svc = builder.AddProject<Projects.Worker>("worker")
    .WithEndpoint("http", e => e.IsProxied = true)
    .WithReplicas(3);
Defensive patterns

Strategy: validation

Validate before calling

// Before running, assert endpoint/replica compatibility
if (resource.GetReplicaCount() > 1)
{
    foreach (var ep in resource.Annotations.OfType<EndpointAnnotation>())
        if (!ep.IsProxied)
            throw new InvalidOperationException($"{resource.Name}: unproxied endpoint '{ep.Name}' cannot be combined with replicas.");
}

Try / catch

try
{
    appHost.Run();
}
catch (InvalidOperationException ex) when (ex.Message.Contains("multiple replicas and a proxy-less endpoint"))
{
    // fix endpoint/replica config before rerun
}

Prevention

When it happens

Trigger: Calling WithReplicas(n>1) on a non-container resource (executable/project) that also has an endpoint created with WithEndpoint(..., isProxied: false) (or the endpoint defaults to unproxied), during AddServicesProducedInfo when DCP services are being built.

Common situations: Scaling out a console/executable project for throughput while having earlier switched the endpoint to isProxied:false to reduce latency; template or sample code where a teammate added replicas without noticing an existing unproxied endpoint annotation.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/Dcp/DcpModelUtilities.cs:71

        IEnumerable<IAppResource> appResources)
        where TDcpResource : CustomResource, IKubernetesStaticMetadata
    {
        var modelResource = appResource.ModelResource;
        var modelResourceName = modelResource.Name ?? "(unknown)";

        var servicesProduced = appResources.OfType<ServiceWithModelResource>().Where(r => r.ModelResource == modelResource);
        foreach (var sp in servicesProduced)
        {
            var ea = sp.EndpointAnnotation;
            ValidateEndpointPorts(modelResource, ea);

            if (!modelResource.IsContainer())
            {
                if (!ea.IsProxied)
                {
                    if (HasMultipleReplicas(appResource.DcpResource))
                    {
                        throw new InvalidOperationException($"Resource '{modelResourceName}' uses multiple replicas and a proxy-less endpoint '{ea.Name}'. These features do not work together.");
                    }
                }
                else
                {
                    Debug.Assert(ea.IsProxied);

                    if (ea.TargetPort is int && ea.Port is int && ea.TargetPort == ea.Port)
                    {
                        throw new InvalidOperationException(
                            $"The endpoint '{ea.Name}' for resource '{modelResourceName}' requested a proxy ({nameof(ea.IsProxied)} is true). Non-container resources cannot be proxied when both {nameof(ea.TargetPort)} and {nameof(ea.Port)} are specified with the same value.");
                    }

                    if (HasMultipleReplicas(appResource.DcpResource) && ea.TargetPort is int)
                    {
                        throw new InvalidOperationException(
                            $"Resource '{modelResourceName}' can have multiple replicas, and it uses endpoint '{ea.Name}' that has {nameof(ea.TargetPort)} property set. Each replica must have a unique port; setting {nameof(ea.TargetPort)} is not allowed.");
                    }
                }

View on GitHub (pinned to 25830f84bd)