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

Pass a concrete header name to TakeHeader.

dotnet/yarp · error · ArgumentException

'headerName' cannot be null or empty.

Error message

'headerName' cannot be null or empty.

What it means

RequestTransform.TakeHeader is a static helper that extracts and removes a header value from the proxy request (or content, or HttpContext). It throws ArgumentException when headerName is null or empty because it cannot look up a header without a name. Custom transforms calling TakeHeader with an empty name hit this.

Source

Thrown at src/ReverseProxy/Transforms/RequestTransform.cs:34

    /// <summary>
    /// Transforms any of the available fields before building the outgoing request.
    /// </summary>
    public abstract ValueTask ApplyAsync(RequestTransformContext context);

    /// <summary>
    /// Removes and returns the current header value by first checking the HttpRequestMessage,
    /// then the HttpContent, and falling back to the HttpContext only if
    /// <see cref="RequestTransformContext.HeadersCopied"/> is not set.
    /// This ordering allows multiple transforms to mutate the same header.
    /// </summary>
    /// <param name="context">The transform context.</param>
    /// <param name="headerName">The name of the header to take.</param>
    /// <returns>The requested header value, or StringValues.Empty if none.</returns>
    public static StringValues TakeHeader(RequestTransformContext context, string headerName)
    {
        if (string.IsNullOrEmpty(headerName))
        {
            throw new ArgumentException($"'{nameof(headerName)}' cannot be null or empty.", nameof(headerName));
        }

        var proxyRequest = context.ProxyRequest;

        if (RequestUtilities.TryGetValues(proxyRequest.Headers, headerName, out var existingValues))
        {
            proxyRequest.Headers.Remove(headerName);
        }
        else if (proxyRequest.Content is { } content && RequestUtilities.TryGetValues(content.Headers, headerName, out existingValues))
        {
            content.Headers.Remove(headerName);
        }
        else if (!context.HeadersCopied)
        {
            existingValues = context.HttpContext.Request.Headers[headerName];
        }

        return existingValues;

View on GitHub (pinned to bd11867bee)

Solutions

Pass a concrete header name to TakeHeader.
Skip empty entries when iterating over header-name collections.
Coalesce null/empty to a default header name if applicable, or skip the transform step.

Example fix

// before
var val = RequestTransform.TakeHeader(context, headerName /* may be empty */);
// after
if (!string.IsNullOrEmpty(headerName))
{
    var val = RequestTransform.TakeHeader(context, headerName);
}

Defensive patterns

Strategy: validation

Validate before calling

if (string.IsNullOrEmpty(headerName))
{
    // skip or log; do not call TakeHeader with an empty name
    return;
}
var value = RequestTransform.TakeHeader(context, headerName);

Type guard

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

Prevention

In custom transforms, always guard TakeHeader calls with a null/empty check.
When iterating header-name collections, filter out empty strings first.
Write a unit test that passes an empty header name to your custom transform to verify graceful handling.

When it happens

Trigger: A custom RequestTransform implementation calling `RequestTransform.TakeHeader(context, headerName)` where headerName is null or empty. This is a developer-API path, not config-driven; it is hit when writing custom transform logic.

Common situations: A custom transform that iterates over a list of header names and one entry is empty; a transform that takes headerName from a route value that resolved to empty; copy-paste of a transform stub without filling in the name.

Related errors

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