dotnet/yarp · error · ArgumentException

'headerName' cannot be null or empty.

Error message

'headerName' cannot be null or empty.

What it means

ResponseHeaderValueTransform's constructor validates headerName (non-null/non-empty) and value (non-null via ArgumentNullException). The transform sets or appends a simple response header value, so both the name and the value must be concrete. A ResponseCondition controls when it applies.

Source

Thrown at src/ReverseProxy/Transforms/ResponseHeaderValueTransform.cs:19

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

/// <summary>
/// Sets or appends simple response header values.
/// </summary>
public class ResponseHeaderValueTransform : ResponseTransform
{
    public ResponseHeaderValueTransform(string headerName, string value, bool append, ResponseCondition condition)
    {
        if (string.IsNullOrEmpty(headerName))
        {
            throw new ArgumentException($"'{nameof(headerName)}' cannot be null or empty.", nameof(headerName));
        }

        HeaderName = headerName;
        ArgumentNullException.ThrowIfNull(value);
        Value = value;
        Append = append;
        Condition = condition;
    }

    internal ResponseCondition Condition { get; }

    internal bool Append { get; }

    internal string HeaderName { get; }

    internal string Value { get; }

    // Assumes the response status code has been set on the HttpContext already.

View on GitHub (pinned to bd11867bee)

Solutions

1. Pass a non-empty header name such as "X-Custom-Header".
2. Ensure the config ResponseHeader value is populated.
3. Validate headerName at the call site before constructing.

Example fix

// before
new ResponseHeaderValueTransform("", "v", false, ResponseCondition.Always);
// after
new ResponseHeaderValueTransform("X-Custom-Header", "v", false, ResponseCondition.Always);

if (string.IsNullOrEmpty(headerName))
    throw new InvalidOperationException("Response header name is required.");
if (value is null)
    throw new InvalidOperationException("Response header value is required.");
var t = new ResponseHeaderValueTransform(headerName, value, append, condition);

static bool IsValidHeaderAndValue(string? name, string? value)
    => !string.IsNullOrWhiteSpace(name) && value is not null;

When it happens

Trigger: Constructing `new ResponseHeaderValueTransform(headerName, value, append, condition)` where headerName is null or empty. Via config this is the 'ResponseHeader' key value; an empty string triggers it.

Common situations: Config `{ "ResponseHeader": "", "Set": "x" }`; a programmatic transform registration with an empty header name; refactoring that cleared the variable.

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