microsoft/aspire · error · ArgumentException

Cannot tunnel endpoint

Error message

Cannot tunnel endpoint '{targetEndpointAnnotation.Name}' with host '{targetEndpointAnnotation.TargetHost}' on resource '{targetResource.Name}' because it is not a localhost endpoint.

What it means

Dev tunnels can only forward traffic for endpoints whose target host is localhost (or the .localhost TLD). When the referenced endpoint annotation already exists on the resource and its TargetHost is not localhost, AddDevTunnelPort throws ArgumentException because tunneling a non-localhost binding is not supported. This stops configurations that would publish internal or external hostnames through a dev tunnel.

Solutions

Change the target endpoint so its host is localhost (default) — remove custom host configuration such as WithEndpoint host overrides.
Use a different, localhost-bound endpoint on the resource as the tunnel target.
If remote forwarding is genuinely needed, use dev tunnel CLI features outside the Aspire builder instead of WithReference.

Example fix

// before
var api = builder.AddProject<Projects.Api>("api")
    .WithEndpoint("https", e => e.TargetHost = "mybox.example.com");
var tunnel = builder.AddDevTunnel("t").WithReference(api.GetEndpoint("https"));
// after (keep default localhost target)
var api = builder.AddProject<Projects.Api>("api").WithHttpsEndpoint();
var tunnel = builder.AddDevTunnel("t").WithReference(api.GetEndpoint("https"));

Defensive patterns

Strategy: validation

Validate before calling

// before tunneling, confirm the endpoint host is localhost
if (!EndpointHostHelpers.IsLocalhostOrLocalhostTld(endpoint.TargetHost))
    throw new InvalidOperationException($"Endpoint {endpoint.EndpointName} host '{endpoint.TargetHost}' is not localhost; cannot tunnel");

Prevention

Do not override TargetHost on endpoints that will be tunneled
Keep tunneled endpoints on their default localhost binding
Document that dev tunnels only forward localhost-bound endpoints

When it happens

Trigger: Calling WithReference(devTunnel, endpoint) where the target resource's endpoint was configured with a non-localhost TargetHost, e.g. via WithEndpoint with a custom host, or an endpoint annotation whose TargetHost resolves to a machine name or domain rather than localhost.

Common situations: Resources configured for external binding during development (e.g. endpoints bound to a LAN hostname or custom domain); copied project setups where someone set the host explicitly; integrating with services that register remote endpoints.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.DevTunnels/DevTunnelResourceBuilderExtensions.cs:588

        DevTunnelPortOptions? portOptions)
    {
        var tunnel = tunnelBuilder.Resource;
        var targetResource = targetEndpoint.Resource;

        if (tunnel.Ports.FirstOrDefault(p => p.TargetEndpoint == targetEndpoint) is { } existingPort)
        {
            // Port already added to the tunnel for this endpoint
            throw new ArgumentException($"Target endpoint '{targetEndpoint.EndpointName}' on resource '{targetEndpoint.Resource.Name}' has already been added to dev tunnel '{tunnel.Name}'.", nameof(targetEndpoint));
        }

        if (targetEndpoint.Resource.Annotations.OfType<EndpointAnnotation>()
            .SingleOrDefault(a => string.Equals(a.Name, targetEndpoint.EndpointName, StringComparisons.EndpointAnnotationName)) is { } targetEndpointAnnotation)
        {
            // The target endpoint already exists so let's ensure it's target is localhost
            if (!EndpointHostHelpers.IsLocalhostOrLocalhostTld(targetEndpointAnnotation.TargetHost))
            {
                // Target endpoint is not localhost so can't be tunneled
                throw new ArgumentException($"Cannot tunnel endpoint '{targetEndpointAnnotation.Name}' with host '{targetEndpointAnnotation.TargetHost}' on resource '{targetResource.Name}' because it is not a localhost endpoint.", nameof(targetEndpoint));
            }
        }

        portOptions ??= new();
        if (portOptions.Protocol is { } proto && proto is not "http" and not "https" and not "auto")
        {
            throw new ArgumentException($"Invalid protocol '{proto}' specified in port options. Supported protocols are 'http', 'https', or 'auto'. Set protocol to null to use the endpoint's scheme.", nameof(portOptions));
        }
        portOptions.Protocol ??= targetEndpoint.Scheme switch
        {
            "https" or "http" => targetEndpoint.Scheme,
            _ => throw new ArgumentException($"Cannot tunnel endpoint '{targetEndpoint.EndpointName}' on resource '{targetResource.Name}' because it uses the unsupported scheme '{targetEndpoint.Scheme}'. Only 'http' and 'https' endpoints can be tunneled."),
        };
        portOptions.Description ??= $"{targetResource.Name}/{targetEndpoint.EndpointName}";

        var portName = $"{tunnel.Name}-{targetResource.Name}-{targetEndpoint.EndpointName}";
        portOptions.Labels ??= [];
        portOptions.Labels.Add(targetResource.Name);

View on GitHub (pinned to 25830f84bd)