What causes "'headerName' cannot be null or empty." in dotnet/yarp?

Supply a real header name, e.g. "X-Unwanted-Header".

dotnet/yarp · error · ArgumentException

'headerName' cannot be null or empty.

Error message

'headerName' cannot be null or empty.

What it means

RequestHeaderRemoveTransform's constructor throws ArgumentException when headerName is null or empty. The transform removes a named request header, so it must know which header to target; an empty name has no valid meaning.

Source

Thrown at src/ReverseProxy/Transforms/RequestHeaderRemoveTransform.cs:18

// 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;

namespace Yarp.ReverseProxy.Transforms;

/// <summary>
/// Removes a request header.
/// </summary>
public class RequestHeaderRemoveTransform : RequestTransform
{
    public RequestHeaderRemoveTransform(string headerName)
    {
        if (string.IsNullOrEmpty(headerName))
        {
            throw new ArgumentException($"'{nameof(headerName)}' cannot be null or empty.", nameof(headerName));
        }

        HeaderName = headerName;
    }

    internal string HeaderName { get; }

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

        RemoveHeader(context, HeaderName);

        return default;
    }
}

View on GitHub (pinned to bd11867bee)

Solutions

Supply a real header name, e.g. "X-Unwanted-Header".
Fix the config so the RequestHeaderRemove value is non-empty.
Filter empty strings out of dynamically generated header names before constructing.

Example fix

// before
{ "RequestHeaderRemove": "" }
// after
{ "RequestHeaderRemove": "X-Unwanted-Header" }

Defensive patterns

Strategy: validation

Validate before calling

if (string.IsNullOrEmpty(headerName))
    throw new InvalidOperationException("Cannot remove a header without a name.");
var transform = new RequestHeaderRemoveTransform(headerName);

Type guard

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

Prevention

Filter empty entries out of dynamic header-name lists before constructing transforms.
Validate config values are non-empty before they reach the transform pipeline.
Use context.AddRequestHeaderRemove from validated config rather than constructing directly.

When it happens

Trigger: Constructing `new RequestHeaderRemoveTransform(headerName)` with a null/empty string. Reaches this constructor through context.AddRequestHeaderRemove when a config transform supplies an empty 'RequestHeaderRemove' value.

Common situations: Config entry `{ "RequestHeaderRemove": "" }`; a programmatic AddTransform using an uninitialised variable; a dynamic header list that yields an empty entry.

Related errors

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