dotnet/yarp · error · ArgumentException

'headerName' cannot be null or empty.

Error message

'headerName' cannot be null or empty.

What it means

RequestHeaderXForwardedForTransform's constructor throws ArgumentException for a null/empty headerName. This transform writes the client remote IP into a forwarded header (commonly X-Forwarded-For), so the target header name is required. A Debug.Assert also verifies the action is not Off.

Source

Thrown at src/ReverseProxy/Transforms/RequestHeaderXForwardedForTransform.cs:25

using Microsoft.Extensions.Primitives;

namespace Yarp.ReverseProxy.Transforms;

/// <summary>
/// Sets or appends the X-Forwarded-For header with the previous client's IP address.
/// </summary>
public class RequestHeaderXForwardedForTransform : RequestTransform
{
    /// <summary>
    /// Creates a new transform.
    /// </summary>
    /// <param name="headerName">The header name.</param>
    /// <param name="action">Action to applied to the header.</param>
    public RequestHeaderXForwardedForTransform(string headerName, ForwardedTransformActions action)
    {
        if (string.IsNullOrEmpty(headerName))
        {
            throw new ArgumentException($"'{nameof(headerName)}' cannot be null or empty.", nameof(headerName));
        }

        HeaderName = headerName;
        Debug.Assert(action != ForwardedTransformActions.Off);
        TransformAction = action;
    }

    internal string HeaderName { get; }

    internal ForwardedTransformActions TransformAction { get; }

    /// <inheritdoc/>
    public override ValueTask ApplyAsync(RequestTransformContext context)
    {
        ArgumentNullException.ThrowIfNull(context);

        string? remoteIp = null;
        var remoteIpAddress = context.HttpContext.Connection.RemoteIpAddress;

View on GitHub (pinned to bd11867bee)

Solutions

1. Pass a real header name such as "X-Forwarded-For".
2. If building dynamically, default to the conventional name when the variable is empty.
3. Guard against null/empty before constructing.

Example fix

// before
new RequestHeaderXForwardedForTransform("", ForwardedTransformActions.Set);
// after
new RequestHeaderXForwardedForTransform("X-Forwarded-For", ForwardedTransformActions.Set);

if (string.IsNullOrEmpty(headerName))
    headerName = "X-Forwarded-For"; // or reject
var t = new RequestHeaderXForwardedForTransform(headerName, action);

static bool IsValidHeaderName(string? name)
    => !string.IsNullOrWhiteSpace(name);

When it happens

Trigger: Constructing `new RequestHeaderXForwardedForTransform(headerName, action)` with headerName null/empty. Typically reached when a custom factory or AddTransform callback supplies an empty header name; the built-in forwarded-header factory supplies the configured name.

Common situations: Programmatic AddTransform with an uninitialised header-name variable; a custom config extension that forwards an empty string; refactoring that dropped the header name.

Related errors

• 'headerName' cannot be null or empty.
• 'headerName' 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/27798776ac7002c5. Report an issue: GitHub.