dotnet/yarp · error · ArgumentException

'key' cannot be null or empty.

Error message

'key' cannot be null or empty.

What it means

Thrown by the abstract QueryParameterTransform base constructor when `key` is null or empty. All query-parameter transforms (Set/Append/Remove/Route/Static) derive from this, so a blank key is caught centrally. Re-checks by subclasses produce more specific messages, but the base is the final guard.

Source

Thrown at src/ReverseProxy/Transforms/QueryParameterTransform.cs:16

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

public abstract class QueryParameterTransform : RequestTransform
{
    public QueryParameterTransform(QueryStringTransformMode mode, string key)
    {
        if (string.IsNullOrEmpty(key))
        {
            throw new ArgumentException($"'{nameof(key)}' cannot be null or empty.", nameof(key));
        }

        Mode = mode;
        Key = key;
    }

    internal QueryStringTransformMode Mode { get; }

    internal string Key { get; }

    /// <inheritdoc/>
    public override ValueTask ApplyAsync(RequestTransformContext context)
    {
        ArgumentNullException.ThrowIfNull(context);

        var value = GetValue(context);
        if (value is not null)
        {

View on GitHub (pinned to bd11867bee)

Solutions

1. Provide a non-empty query-parameter name when constructing any QueryParameterTransform subclass.
2. Validate the key upstream in config binding.
3. If writing a subclass, document that key must be non-empty.

Example fix

// before
: base(QueryStringTransformMode.Set, "")
// after
: base(QueryStringTransformMode.Set, "q")

ArgumentException.ThrowIfNullOrEmpty(key);

static bool IsValidQueryKey(string? key) => !string.IsNullOrEmpty(key);

When it happens

Trigger: Constructing any subclass of QueryParameterTransform with a null/empty `key`, where the subclass does not itself short-circuit the check first.

Common situations: Direct instantiation of a query transform subclass with an empty key, or a subclass that relies solely on the base validation.

Related errors

• '{nameof(key)}' cannot be null or empty.
• '{nameof(routeValueKey)}' cannot be null or empty.
• '{nameof(key)}' cannot be null or empty.
• 'key' cannot be null or empty.
• '{nameof(fromMethod)}' cannot be null or empty.

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