microsoft/aspire · error · InvalidOperationException

The endpoint ' ' for resource ' ' requested a proxy…

Error message

The endpoint '{ea.Name}' for resource '{modelResourceName}' requested a proxy (IsProxied is true). Non-container resources cannot be proxied when both TargetPort and Port are specified with the same value.

What it means

For a non-container resource with a proxied endpoint, Aspire requires that the port be free to be allocated; specifying both an explicit TargetPort and an explicit Port with the same value defeats the proxy's ability to choose a port and would collide across replicas. It throws when both are set and equal.

Solutions

  1. Remove the explicit port (public Port) argument and let the proxy allocate one: WithEndpoint(name: "http", targetPort: 8080).
  2. If the process must listen on a fixed port with no proxy, set isProxied: false and specify only targetPort.
  3. If the fixed public port is required, make the endpoint unproxied and ensure replicas stay at 1.

Example fix

// before
.WithEndpoint("http", e => { e.Port = 8080; e.TargetPort = 8080; e.IsProxied = true; })
// after
.WithEndpoint("http", e => { e.TargetPort = 8080; e.IsProxied = true; })
Defensive patterns

Strategy: validation

Validate before calling

var proxiedFixedPort = endpoints.Where(e => e.IsProxied)
    .Any(e => e.TargetPort is int t && e.Port is int p && t == p);
if (proxiedFixedPort) throw new InvalidOperationException("Proxied endpoints must not pin both Port and TargetPort to the same value.");

Try / catch

try
{
    builder.Build().Run();
}
catch (InvalidOperationException ex) when (ex.Message.Contains("cannot be proxied when both"))
{
    // drop the explicit Port or switch to isProxied:false
}

Prevention

When it happens

Trigger: AddProject/AddExecutable resource with WithEndpoint(name, port: 8080, targetPort: 8080) (or WithHttpEndpoint equivalents) while IsProxied remains true, evaluated in AddServicesProducedInfo.

Common situations: Porting an app from direct Kestrel/port config where the listen port equals the public port; copy-pasting endpoint config from container setups where fixed port:targetPort pairs are normal.

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/0418c997ce5c9f63. Report an issue: GitHub.

Appendix: source

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

            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.");
                    }
                }
            }

            var spAnn = new ServiceProducerAnnotation(sp.Service.Metadata.Name);
            (spAnn.Address, _) = NormalizeTargetHost(ea.TargetHost);
            spAnn.Port = ea.TargetPort;
            appResource.DcpResource.AnnotateAsObjectList(CustomResource.ServiceProducerAnnotation, spAnn);
            appResource.ServicesProduced.Add(sp);
        }

View on GitHub (pinned to 25830f84bd)