dotnet/yarp · error · ArgumentException

Invalid destination prefix.

Error message

Invalid destination prefix.

What it means

Thrown by HttpForwarder.SendAsync when the destinationPrefix is null or shorter than 8 characters. The minimum valid prefix like "http://a" is 8 characters, so anything shorter cannot be a well-formed absolute URI. The forwarder needs a valid base address to construct the upstream request.

Source

Thrown at src/ReverseProxy/Forwarder/HttpForwarder.cs:125

        ArgumentNullException.ThrowIfNull(requestConfig);
        ArgumentNullException.ThrowIfNull(transformer);

        if (RequestUtilities.IsResponseSet(context.Response))
        {
            throw new InvalidOperationException("The request cannot be forwarded, the response has already started");
        }

        // HttpClient overload for SendAsync changes response behavior to fully buffered which impacts performance
        // See discussion in https://github.com/dotnet/yarp/issues/458
        if (httpClient is HttpClient)
        {
            throw new ArgumentException($"The http client must be of type HttpMessageInvoker, not HttpClient", nameof(httpClient));
        }

        // "http://a".Length = 8
        if (destinationPrefix is null || destinationPrefix.Length < 8)
        {
            throw new ArgumentException("Invalid destination prefix.", nameof(destinationPrefix));
        }

        ForwarderTelemetry.Log.ForwarderStart(destinationPrefix);

        var activityCancellationSource = ActivityCancellationTokenSource.Rent(requestConfig?.ActivityTimeout ?? DefaultTimeout, context.RequestAborted, cancellationToken);
        try
        {
            var isClientHttp2OrGreater = ProtocolHelper.IsHttp2OrGreater(context.Request.Protocol);

            // NOTE: We heuristically assume gRPC-looking requests may require streaming semantics.
            // See https://github.com/dotnet/yarp/issues/118 for design discussion.
            var isStreamingRequest = isClientHttp2OrGreater && ProtocolHelper.IsGrpcContentType(context.Request.ContentType);

            HttpRequestMessage? destinationRequest = null;
            StreamCopyHttpContent? requestContent = null;
            HttpResponseMessage destinationResponse;
            try
            {

View on GitHub (pinned to bd11867bee)

Solutions

1. Set DestinationConfig.Address to a fully-qualified absolute URL (e.g., "http://host:port/path") of at least 8 characters.
2. Validate the address has a scheme (http/https) and host before passing to SendAsync.
3. If using config substitution, ensure the substituted value is non-empty and well-formed.

Example fix

// before
"Destinations": { "d1": { "Address": "http://" } }
// after
"Destinations": { "d1": { "Address": "http://backend.local:8080/" } }

if (string.IsNullOrEmpty(destinationPrefix) || destinationPrefix.Length < 8 || !Uri.IsWellFormedUriString(destinationPrefix, UriKind.Absolute))
    throw new ArgumentException("Invalid destination prefix.", nameof(destinationPrefix));

static bool IsValidDestinationPrefix(string? s) =>
    !string.IsNullOrEmpty(s) && s.Length >= 8 && Uri.IsWellFormedUriString(s, UriKind.Absolute);

try { await forwarder.SendAsync(context, address, client, reqConfig, transformer, ct); }
catch (ArgumentException ex) when (ex.Message.Contains("Invalid destination prefix"))
{ logger.LogError("Destination address invalid: {Address}", address); context.Response.StatusCode = 502; }

When it happens

Trigger: Passing a destinationPrefix that is null, empty, or a relative/non-absolute URL shorter than 8 chars (e.g., "http://") to SendAsync. Usually the address comes from DestinationConfig.Address.

Common situations: Destination Address misconfigured in appsettings (missing scheme, trailing slash only, placeholder unresolved). Env-var/config substitution producing an empty string. Typo in the destination URL.

Related errors

• Chosen destination has no model set: '{destination.Destinati
• Configuration Filter Error: Substitution for '{lookup}' in c
• A non-empty CustomTransform value is required
• A non-empty CustomMetadata value is required
• The route config format has changed, routes are now objects

AI-assisted analysis of dotnet/yarp@bd11867bee (2026-08-13). Data as JSON: /api/errors/05d7bfa7ffda90b6. Report an issue: GitHub.