What causes "Query parameter values must not be empty." in dotnet/yarp?

Strip empty/null entries before construction using `Where(v => !string.IsNullOrEmpty(v))`.

dotnet/yarp · error · ArgumentNullException

Query parameter values must not be empty.

Error message

Query parameter values must not be empty.

What it means

Thrown by the QueryParameterMatcher constructor when `values` is non-null but contains a null or empty string element (`values.Any(string.IsNullOrEmpty)`). Thrown as ArgumentNullException on the `values` parameter; only reachable for non-Exists modes (Exists with values trips the earlier check).

Source

Thrown at src/ReverseProxy/Routing/QueryParameterMatcher.cs:33

{
    /// <summary>
    /// Creates a new instance.
    /// </summary>
    public QueryParameterMatcher(string name, IReadOnlyList<string>? values, QueryParameterMatchMode mode, bool isCaseSensitive)
    {
        ArgumentException.ThrowIfNullOrEmpty(name);
        if (mode != QueryParameterMatchMode.Exists
            && (values is null || values.Count == 0))
        {
            throw new ArgumentException("Query parameter values must have at least one value.", nameof(values));
        }
        if (mode == QueryParameterMatchMode.Exists && values?.Count > 0)
        {
            throw new ArgumentException($"Query parameter values must not be specified when using '{nameof(QueryParameterMatchMode.Exists)}'.", nameof(values));
        }
        if (values is not null && values.Any(string.IsNullOrEmpty))
        {
            throw new ArgumentNullException(nameof(values), "Query parameter values must not be empty.");
        }

        Name = name;
        Values = values?.ToArray() ?? Array.Empty<string>();
        Mode = mode;
        Comparison = isCaseSensitive ? StringComparison.Ordinal : StringComparison.OrdinalIgnoreCase;
    }

    /// <summary>
    /// Name of the query parameter to look for.
    /// </summary>
    public string Name { get; }

    /// <summary>
    /// Returns a read-only collection of acceptable query parameter values used during routing.
    /// At least one value is required unless <see cref="Mode"/> is set to <see cref="QueryParameterMatchMode.Exists"/>.
    /// </summary>
    public string[] Values { get; }

View on GitHub (pinned to bd11867bee)

Solutions

Strip empty/null entries before construction using `Where(v => !string.IsNullOrEmpty(v))`.
Correct the config to remove blank value tokens.
Validate query-match config blocks for blank values during route validation.

Example fix

// before
new QueryParameterMatcher("t", new[] { "", "x" }, QueryParameterMatchMode.Prefix, false);
// after
new QueryParameterMatcher("t", new[] { "x" }, QueryParameterMatchMode.Prefix, false);

Defensive patterns

Strategy: validation

Validate before calling

values = values?.Where(v => !string.IsNullOrEmpty(v)).ToList();

Type guard

static bool HasNoBlankQueryValues(IReadOnlyList<string>? values) =>
    values is null || values.All(v => !string.IsNullOrEmpty(v));

Prevention

Filter empty entries out of value lists before constructing matchers.
Reject blank query-value tokens in config validation.
Use StringSplitOptions.RemoveEmptyEntries when splitting.

When it happens

Trigger: Calling `new QueryParameterMatcher(name, values, mode, ...)` where `values` includes a null or empty element and mode is a value-matching mode.

Common situations: Config with `"values": [""]` or `[null]`. Splitting a query template string that yields empty segments. Unsanitized user input feeding the matcher.

Related errors

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