dotnet/yarp · error · ArgumentException

'headerName' cannot be null or empty.

Error message

'headerName' cannot be null or empty.

What it means

RequestHeaderRouteValueTransform's constructor validates that headerName is non-null/non-empty (the first guard, before checking routeValueKey). Because the transform sets a request header from a route value, both names are mandatory. A null/empty header name is a programming error that cannot produce a functioning transform.

Source

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

// Licensed to the .NET Foundation under one or more agreements.
// 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;

View on GitHub (pinned to bd11867bee)

Solutions

1. Provide a non-empty header name, e.g. "X-Route-Id".
2. Ensure the RequestHeaderRouteValue config value is populated.
3. Validate headerName at the call site before constructing.

Example fix

// before
new RequestHeaderRouteValueTransform("", routeValueKey, append);
// after
new RequestHeaderRouteValueTransform("X-Route-Id", routeValueKey, append);

if (string.IsNullOrEmpty(headerName))
    throw new InvalidOperationException("headerName is required.");
if (string.IsNullOrEmpty(routeValueKey))
    throw new InvalidOperationException("routeValueKey is required.");
var t = new RequestHeaderRouteValueTransform(headerName, routeValueKey, append);

static bool IsValidHeaderAndRouteKey(string? header, string? route)
    => !string.IsNullOrWhiteSpace(header) && !string.IsNullOrWhiteSpace(route);

When it happens

Trigger: Calling `new RequestHeaderRouteValueTransform(headerName, routeValueKey, append)` where headerName is null or empty. Also reached via context.AddRequestHeaderRouteValue when the 'RequestHeaderRouteValue' config key resolves to an empty string.

Common situations: Config entry `{ "RequestHeaderRouteValue": "", "Set": "x" }`; a programmatic transform with an empty header name variable; refactoring that cleared the header name.

Related errors

• 'routeValueKey' 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/3897db656112d3e6. Report an issue: GitHub.