dotnet/yarp · error · ArgumentException

'headerName' cannot be null or empty.

Error message

'headerName' cannot be null or empty.

What it means

RequestHeaderXForwardedProtoTransform's constructor throws ArgumentException when headerName is null or empty. The transform writes the request scheme (http/https) into a forwarded header such as X-Forwarded-Proto, so the target header name is required. A Debug.Assert also guards that action is not Off.

Source

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

using Microsoft.Extensions.Primitives;

namespace Yarp.ReverseProxy.Transforms;

/// <summary>
/// Sets or appends the X-Forwarded-Proto header with the request's original url scheme.
/// </summary>
public class RequestHeaderXForwardedProtoTransform : 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 RequestHeaderXForwardedProtoTransform(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 scheme = context.HttpContext.Request.Scheme;

        switch (TransformAction)

View on GitHub (pinned to bd11867bee)

Solutions

1. Pass a real header name, e.g. "X-Forwarded-Proto".
2. Source the name from a non-empty config value.
3. Guard the construction call site.

Example fix

// before
new RequestHeaderXForwardedProtoTransform("", ForwardedTransformActions.Set);
// after
new RequestHeaderXForwardedProtoTransform("X-Forwarded-Proto", ForwardedTransformActions.Set);

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

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

When it happens

Trigger: Constructing `new RequestHeaderXForwardedProtoTransform(headerName, action)` with a null/empty headerName. Encountered via a custom factory or programmatic AddTransform with an empty name.

Common situations: Uninitialised header-name variable in a custom transform setup; config extension passing an empty string; refactoring oversight.

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