dotnet/yarp · error · ArgumentException

'headerName' cannot be null or empty.

Error message

'headerName' cannot be null or empty.

What it means

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

Source

Thrown at src/ReverseProxy/Transforms/ResponseTrailerValueTransform.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 trailer values.
/// </summary>
public class ResponseTrailerValueTransform : ResponseTrailersTransform
{
    public ResponseTrailerValueTransform(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 trailer name such as "X-Grpc-Status".
2. Ensure the config ResponseTrailer value is populated.
3. Validate headerName at the call site before constructing.

Example fix

// before
new ResponseTrailerValueTransform("", "v", true, ResponseCondition.Success);
// after
new ResponseTrailerValueTransform("X-Grpc-Status", "v", true, ResponseCondition.Success);

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

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

When it happens

Trigger: Constructing `new ResponseTrailerValueTransform(headerName, value, append, condition)` where headerName is null or empty. Via config this is the 'ResponseTrailer' key value.

Common situations: Config `{ "ResponseTrailer": "", "Set": "x" }`; a programmatic transform with an empty name; refactoring that dropped the name.

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.
• Unexpected parameters for ResponseTrailer: {string.Join(';',

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