microsoft/aspire · error · InvalidOperationException

Service ' ' needs to specify a port for endpoint ' ' since…

Error message

Service '{svc.Metadata.Name}' needs to specify a port for endpoint '{sp.EndpointAnnotation.Name}' since it isn't using a proxy.

What it means

A proxy-less (IsProxied == false) endpoint must have its port specified somewhere — via targetPort on the endpoint or the process listening port — because DCP will not allocate/choose one. When no port is known and the call isn't allowing pending endpoints, Aspire throws.

Solutions

Specify the port explicitly: WithEndpoint(name: "http", targetPort: 5080, isProxied: false).
Make the application listen on that fixed port (Kestrel config/launchSettings) so the endpoint annotation can bind it.
Re-enable the proxy (isProxied: true) if a dynamic port is acceptable.

Example fix

// before
.WithEndpoint("http", e => e.IsProxied = false)
// after
.WithEndpoint("http", e => { e.IsProxied = false; e.TargetPort = 5080; })

Defensive patterns

Strategy: validation

Validate before calling

foreach (var ep in resource.Annotations.OfType<EndpointAnnotation>())
{
    if (!ep.IsProxied && ep.TargetPort is null && ep.Port is null)
        throw new InvalidOperationException($"{resource.Name}: unproxied endpoint '{ep.Name}' needs an explicit port.");
}

Try / catch

try
{
    app.Run();
}
catch (InvalidOperationException ex) when (ex.Message.Contains("needs to specify a port"))
{
    // add targetPort to the unproxied endpoint or re-enable the proxy
}

Prevention

Whenever setting isProxied:false, always pass an explicit targetPort in the same change.
Ensure the app actually listens on the pinned port (Kestrel/launchSettings alignment).
Only use proxy-less endpoints for processes with deterministic listening ports.

When it happens

Trigger: Non-container resource with WithEndpoint(..., isProxied: false) but no targetPort and no resolvable listening port (e.g. project doesn't expose its Kestrel port), when TryAddWorkloadAllocatedEndpoints/ApplyServiceAddressToEndpoint runs with allowPending=false.

Common situations: Switching an endpoint to isProxied:false to skip the proxy while forgetting to pin the port; executables that listen on a random port and never publish it; launchSettings changes removing the port.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

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

        {
            if (allowPending)
            {
                return false;
            }

            // This should never happen; if it does, we have a bug without a workaround for the user.
            // We should have waited for the service to have a complete address before getting here.
            throw new InvalidDataException($"Service {svc.Metadata.Name} should have valid address at this point");
        }

        if (!sp.EndpointAnnotation.IsProxied && allocatedPort is null)
        {
            if (allowPending)
            {
                return false;
            }

            throw new InvalidOperationException($"Service '{svc.Metadata.Name}' needs to specify a port for endpoint '{sp.EndpointAnnotation.Name}' since it isn't using a proxy.");
        }

        if (allocatedPort is null || string.IsNullOrEmpty(svc.AllocatedAddress))
        {
            if (allowPending)
            {
                return false;
            }

            throw new InvalidDataException($"Service {svc.Metadata.Name} should have valid address at this point");
        }

        var (targetHost, bindingMode) = NormalizeTargetHost(sp.EndpointAnnotation.TargetHost);

        sp.EndpointAnnotation.AllocatedEndpoint = new AllocatedEndpoint(
            sp.EndpointAnnotation,
            targetHost,
            allocatedPort.Value,

View on GitHub (pinned to 25830f84bd)