dotnet/yarp · error · ArgumentException

'headerName' cannot be null or empty.

Error message

'headerName' cannot be null or empty.

What it means

RequestHeaderClientCertTransform's constructor rejects a null or empty headerName with ArgumentException. The transform needs a concrete header name to write the base64-encoded client certificate into, so an empty name is a programming error, not a recoverable runtime condition.

Source

Thrown at src/ReverseProxy/Transforms/RequestHeaderClientCertTransform.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>
/// Base64 encodes the client certificate (if any) and sets it as the header value.
/// </summary>
public class RequestHeaderClientCertTransform : RequestTransform
{
    public RequestHeaderClientCertTransform(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);

        var clientCert = context.HttpContext.Connection.ClientCertificate;
        if (clientCert is not null)
        {
            var encoded = Convert.ToBase64String(clientCert.RawData);

View on GitHub (pinned to bd11867bee)

Solutions

1. Pass a non-empty header name such as "X-Client-Cert".
2. If the value comes from config, ensure the config key is populated and not blank.
3. Guard the call site with a null/empty check before constructing the transform.

Example fix

// before
new RequestHeaderClientCertTransform(headerName /* null */);
// after
new RequestHeaderClientCertTransform(
    string.IsNullOrEmpty(headerName) ? "X-Client-Cert" : headerName);

if (string.IsNullOrEmpty(headerName))
    throw new InvalidOperationException("headerName must be set before creating the transform.");
var transform = new RequestHeaderClientCertTransform(headerName);

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

When it happens

Trigger: Calling `new RequestHeaderClientCertTransform(headerName)` where headerName is null, string.Empty, or whitespace-only. In config-driven flow, this fires if a custom factory or AddTransform callback passes an empty value; the built-in factories always supply the header name from config keys.

Common situations: Programmatically adding transforms via AddTransform with a variable that resolved to empty; a config value that is an empty string reaching a custom factory; refactoring that introduced a null assignment.

Related errors

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