microsoft/aspire · error · InvalidOperationException

Endpoint ' ' on resource ' ' does not have a target port.

Error message

Endpoint '{endpointReferenceExpression.Endpoint.EndpointName}' on resource '{resource.TargetResource.Name}' does not have a target port.

What it means

Thrown when constructing an AzureSandboxEndpointPropertyValueProvider for an EndpointProperty.TargetPort expression whose endpoint has no resolvable target port on the target resource. The provider needs the container's internal target port to map sandbox URLs back to the endpoint and cannot proceed without it.

Solutions

Add an explicit target port to the endpoint: .WithHttpEndpoint(port: 8080, targetPort: 8080, name: "http").
Verify the endpoint name in the EndpointReference matches the name passed to WithHttpEndpoint/WithEndpoint.
If the container image exposes a fixed port, set targetPort to that container port explicitly.
Check resource.TargetResource.ResolveEndpoints() in a debug session to see which endpoints/ports were actually registered.

Example fix

// before
builder.AddContainer("api", "image").WithHttpEndpoint(name: "http");
// after
builder.AddContainer("api", "image").WithHttpEndpoint(targetPort: 8080, name: "http");

Defensive patterns

Strategy: validation

Validate before calling

bool HasTargetPort(IResource r, string endpointName) =>
    r.ResolveEndpoints().Any(e => e.EndpointName == endpointName && e.TargetPort is not null);

Try / catch

try { var value = await provider.GetValueAsync(); }
catch (InvalidOperationException ex) { logger.LogError(ex, "Endpoint missing target port"); throw; }

Prevention

Always pass an explicit targetPort when declaring container endpoints used by sandboxes.
Align targetPort with the image's exposed container port.
Keep endpoint names consistent across declarations and references.

When it happens

Trigger: ResolveEndpointTargetPort(resource, endpointName) returns null — the endpoint on resource.TargetResource has no explicit TargetPort and none can be inferred (e.g. an endpoint declared without WithTargetPort or without a container port binding).

Common situations: Declaring `.WithEndpoint(...)` or `.WithHttpEndpoint(...)` without a target port on a container used as an Azure sandbox container; referencing an endpoint name that was renamed or misspelled.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Azure.Sandboxes/AzureSandboxEndpointPropertyValueProvider.cs:35

{
    private readonly AzureSandboxContainerResource _resource;
    private readonly EndpointReferenceExpression _endpointReferenceExpression;
    private readonly AzureSandboxContainerDeployment.SandboxEndpoint? _sandboxEndpoint;
    private readonly int _targetPort;

    public AzureSandboxEndpointPropertyValueProvider(
        AzureSandboxContainerResource resource,
        EndpointReferenceExpression endpointReferenceExpression)
    {
        ArgumentNullException.ThrowIfNull(resource);
        ArgumentNullException.ThrowIfNull(endpointReferenceExpression);

        _resource = resource;
        _endpointReferenceExpression = endpointReferenceExpression;
        if (endpointReferenceExpression.Property == EndpointProperty.TargetPort)
        {
            _targetPort = ResolveEndpointTargetPort(resource, endpointReferenceExpression.Endpoint.EndpointName) ??
                throw new InvalidOperationException($"Endpoint '{endpointReferenceExpression.Endpoint.EndpointName}' on resource '{resource.TargetResource.Name}' does not have a target port.");
        }
        else
        {
            var sandboxEndpoint = ResolveSandboxEndpoint(resource, endpointReferenceExpression.Endpoint);
            _sandboxEndpoint = sandboxEndpoint;
            _targetPort = sandboxEndpoint.TargetPort;
        }
    }

    public string ValueExpression =>
        $"{{{_resource.Name}.endpoints.{_endpointReferenceExpression.Endpoint.EndpointName}.{_endpointReferenceExpression.Property.ToString().ToLowerInvariant()}}}";

    public ValueTask<string?> GetValueAsync(CancellationToken cancellationToken = default)
    {
        return new(GetKnownValueWithoutDeploymentState() ?? throw CreateUnresolvedEndpointException());
    }

    public async ValueTask<string?> GetValueAsync(ValueProviderContext context, CancellationToken cancellationToken = default)

View on GitHub (pinned to 25830f84bd)