microsoft/aspire · error · ArgumentException

Cannot tunnel endpoint

Error message

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.

What it means

When no explicit protocol is set in portOptions, AddDevTunnelPort infers it from the endpoint's Scheme. If the scheme is neither 'http' nor 'https' (e.g. 'tcp', 'ftp'), there is no valid tunnel protocol to map to, so an ArgumentException is thrown without a parameter name. Dev tunnels only support HTTP/HTTPS forwarding.

Solutions

1. Tunnel only http/https endpoints; pick that endpoint on the resource.
2. Do not set Protocol manually for non-HTTP ports — it will not help; the transport itself is unsupported.
3. Use an alternative forwarding mechanism (e.g. port-forward tooling) for raw TCP services.

Example fix

// before
var pg = builder.AddPostgres("pg");
var tunnel = builder.AddDevTunnel("t").WithReference(pg.GetEndpoint("tcp")); // tcp unsupported
// after
var tunnel = builder.AddDevTunnel("t").WithReference(api.GetEndpoint("https")); // http/https only

// only tunnel http/https endpoints
if (endpoint.Scheme is not ("http" or "https"))
    throw new InvalidOperationException($"Endpoint {endpoint.EndpointName} scheme '{endpoint.Scheme}' cannot be tunneled");

When it happens

Trigger: Referencing an endpoint whose scheme is not http/https in WithReference(devTunnel, endpoint) without setting portOptions.Protocol — e.g. WithEndpoint("tcp", e => e.Scheme = "tcp") then tunneling that endpoint.

Common situations: Tunneling database/TCP ports (Postgres, Redis) that developers assume dev tunnels support; custom endpoints declared with non-HTTP schemes.

Related errors

• Cannot tunnel endpoint
• Could not create for resource ' ' as the endpoint with name…
• Could not create HTTP command for resource
• Could not create HTTP health check for resource
• Endpoint ' ' on resource ' ' uses transport ' '. Azure…

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

Appendix: source

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

            .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);
        portOptions.Labels.Add(targetEndpoint.EndpointName);

        if (!TryValidateLabels(portOptions.Labels, out var errorMessage))
        {
            throw new ArgumentException(errorMessage, nameof(portOptions));
        }

        var portResource = new DevTunnelPortResource(
            portName,
            tunnel,
            targetEndpoint,
            portOptions);

View on GitHub (pinned to 25830f84bd)