dotnet/yarp · error · ArgumentException

'routeValueKey' cannot be null or empty.

Error message

'routeValueKey' cannot be null or empty.

What it means

The second guard in RequestHeaderRouteValueTransform's constructor: after headerName passes, routeValueKey is checked and must be non-null/non-empty. The transform reads a value from HttpContext.Request.RouteValues by this key, so an empty key cannot locate anything.

Source

Thrown at src/ReverseProxy/Transforms/RequestHeaderRouteValueTransform.cs:20

// The .NET Foundation licenses this file to you under the MIT license.

using System;

namespace Yarp.ReverseProxy.Transforms;

public class RequestHeaderRouteValueTransform : RequestHeaderTransform
{
    public RequestHeaderRouteValueTransform(string headerName, string routeValueKey, bool append)
        : base(headerName, append)
    {
        if (string.IsNullOrEmpty(headerName))
        {
            throw new ArgumentException($"'{nameof(headerName)}' cannot be null or empty.", nameof(headerName));
        }

        if (string.IsNullOrEmpty(routeValueKey))
        {
            throw new ArgumentException($"'{nameof(routeValueKey)}' cannot be null or empty.", nameof(routeValueKey));
        }

        RouteValueKey = routeValueKey;
    }

    internal string RouteValueKey { get; }

    protected override string? GetValue(RequestTransformContext context)
    {
        var routeValues = context.HttpContext.Request.RouteValues;
        if (!routeValues.TryGetValue(RouteValueKey, out var value))
        {
            return null;
        }

        return value?.ToString();
    }
}

View on GitHub (pinned to bd11867bee)

Solutions

1. Supply a route-value key that exists in your route template, e.g. "userId".
2. Make sure the 'Set'/'Append' value in config is non-empty.
3. Confirm the key matches a {param} in the route pattern so the transform resolves a value.

Example fix

// before
{ "RequestHeaderRouteValue": "X-User", "Set": "" }
// after
{ "RequestHeaderRouteValue": "X-User", "Set": "userId" }

if (string.IsNullOrEmpty(routeValueKey))
    throw new InvalidOperationException("routeValueKey must reference a route parameter.");
var t = new RequestHeaderRouteValueTransform(headerName, routeValueKey, append);

static bool IsValidRouteKey(string? key)
    => !string.IsNullOrWhiteSpace(key);

When it happens

Trigger: Constructing `new RequestHeaderRouteValueTransform(headerName, routeValueKey, append)` where routeValueKey is null or empty. Via config this is the value of the 'Set'/'Append' sibling under a 'RequestHeaderRouteValue' transform.

Common situations: Config `{ "RequestHeaderRouteValue": "X-Hdr", "Set": "" }`; a programmatic call where the route-value key variable was never assigned; mismatched route parameter name.

Related errors

• 'headerName' cannot be null or empty.
• '{nameof(routeValueKey)}' cannot be null or empty.
• 'headerName' cannot be null or empty.
• 'headerName' cannot be null or empty.
• 'headerName' cannot be null or empty.

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