dotnet/yarp · error · ArgumentException

'headerName' cannot be null or empty.

Error message

'headerName' cannot be null or empty.

What it means

RequestHeaderXForwardedPrefixTransform's constructor rejects a null/empty headerName with ArgumentException. The transform sets/appends the request's original PathBase into the named header (e.g. X-Forwarded-Prefix), so the header name is mandatory. A Debug.Assert ensures the action is not Off.

Source

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

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

using System;
using System.Diagnostics;
using System.Threading.Tasks;
using Microsoft.Extensions.Primitives;

namespace Yarp.ReverseProxy.Transforms;

/// <summary>
/// Sets or appends the X-Forwarded-Prefix header with the request's original PathBase.
/// </summary>
public class RequestHeaderXForwardedPrefixTransform : RequestTransform
{
    public RequestHeaderXForwardedPrefixTransform(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);

        var pathBase = context.HttpContext.Request.PathBase;

        switch (TransformAction)

View on GitHub (pinned to bd11867bee)

Solutions

1. Supply a concrete header name like "X-Forwarded-Prefix".
2. Ensure the value comes from a non-empty config/source.
3. Validate before constructing.

Example fix

// before
new RequestHeaderXForwardedPrefixTransform(null, ForwardedTransformActions.Append);
// after
new RequestHeaderXForwardedPrefixTransform("X-Forwarded-Prefix", ForwardedTransformActions.Append);

if (string.IsNullOrEmpty(headerName))
    headerName = "X-Forwarded-Prefix";
var t = new RequestHeaderXForwardedPrefixTransform(headerName, action);

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

When it happens

Trigger: Calling `new RequestHeaderXForwardedPrefixTransform(headerName, action)` where headerName is null or empty. Hit through a custom factory or AddTransform callback that passes an empty name.

Common situations: Programmatic transform registration with an empty header-name variable; a config-driven custom factory emitting a blank name; refactoring that introduced a null.

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/58b22c252f9039a0. Report an issue: GitHub.