dotnet/yarp · error · ArgumentException

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

Error message

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

What it means

Thrown by the QueryParameterRouteTransform constructor when `routeValueKey` is null or empty. This transform pulls a value from route values by name; a blank route-value key cannot resolve a value, so it is rejected as ArgumentException.

Source

Thrown at src/ReverseProxy/Transforms/QueryParameterFromRouteTransform.cs:20

// The .NET Foundation licenses this file to you under the MIT license.

using System;

namespace Yarp.ReverseProxy.Transforms;

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

        if (string.IsNullOrEmpty(routeValueKey))
        {
            throw new ArgumentException($"'{nameof(routeValueKey)}' cannot be null or empty.", nameof(routeValueKey));
        }

        RouteValueKey = routeValueKey;
    }

    internal string RouteValueKey { get; }

    /// <inheritdoc/>
    protected override string? GetValue(RequestTransformContext context)
    {
        var routeValues = context.HttpContext.Request.RouteValues;
        if (!routeValues.TryGetValue(RouteValueKey, out var value))
        {
            return null;
        }

        return value?.ToString();
    }

View on GitHub (pinned to bd11867bee)

Solutions

1. Provide a non-empty `routeValueKey` that matches a parameter in the route template.
2. Cross-check the route template (`{userId}`) against the configured routeValueKey.
3. Validate config before constructing the transform.

Example fix

// before
new QueryParameterRouteTransform(QueryStringTransformMode.Set, "uid", "");
// after
new QueryParameterRouteTransform(QueryStringTransformMode.Set, "uid", "userId");

ArgumentException.ThrowIfNullOrEmpty(routeValueKey);

static bool RouteHasParameter(string template, string routeValueKey) =>
    template.Contains($"{{{routeValueKey}}}");

When it happens

Trigger: Constructing `new QueryParameterRouteTransform(mode, key, routeValueKey)` with `routeValueKey` null/empty, or transform config that omits the route value key.

Common situations: Config sets a query-from-route transform but the route parameter name is missing or misspelled. The route template does not define the referenced parameter.

Related errors

• '{nameof(key)}' cannot be null or empty.
• '{nameof(key)}' cannot be null or empty.
• 'key' cannot be null or empty.
• 'key' 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/792d4206b25c862f. Report an issue: GitHub.