dotnet/yarp · error · ArgumentException

'headerName' cannot be null or empty.

Error message

'headerName' cannot be null or empty.

What it means

RequestHeaderTransform (the abstract base for header-based request transforms) rejects a null/empty headerName in its protected constructor. All derived header transforms inherit this guard, so any subclass constructed without a concrete header name fails here.

Source

Thrown at src/ReverseProxy/Transforms/RequestHeaderTransform.cs:16

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

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

namespace Yarp.ReverseProxy.Transforms;

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

        Append = append;
        HeaderName = headerName;
    }

    internal bool Append { get; }
    internal string HeaderName { get; }

    public override ValueTask ApplyAsync(RequestTransformContext context)
    {
        ArgumentNullException.ThrowIfNull(context);

        var value = GetValue(context);
        if (value is null)
        {
            return default;
        }

View on GitHub (pinned to bd11867bee)

Solutions

1. Pass a concrete header name to the base constructor.
2. Populate the config 'RequestHeader' value with a real header name.
3. Add a guard at the construction call site.

Example fix

// before
base(headerName: "", append: true)
// after
base(headerName: "X-Custom", append: true)

if (string.IsNullOrEmpty(headerName))
    throw new InvalidOperationException("A header name is required for RequestHeaderTransform.");
// then construct the derived transform

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

When it happens

Trigger: Deriving from RequestHeaderTransform (or using RequestHeaderValueTransform) and passing a null/empty headerName to the base constructor. Reached via config when the header name portion of a RequestHeader transform resolves to empty.

Common situations: A custom RequestHeaderTransform subclass whose header-name argument is uninitialised; config with an empty RequestHeader value; a programmatic AddTransform callback with a cleared variable.

Related errors

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