What causes "Cannot have empty query parameter names." in dotnet/aspnetcore?

Validate that the parameter name is non-empty before calling GetUriWithQueryParameter(s); guard with if (string.IsNullOrWhiteSpace(name)).

dotnet/aspnetcore · error · InvalidOperationException

Cannot have empty query parameter names.

Error message

Cannot have empty query parameter names.

What it means

Thrown by the QueryParameterSource(string name) constructor when name is null or empty. The extension API that builds query strings (GetUriWithQueryParameter[s]) refuses empty parameter names because they cannot be encoded into a well-formed query string (a '?' with no name is ambiguous). The check is shared by the single-value and multi-value parameter sources.

Solutions

Validate that the parameter name is non-empty before calling GetUriWithQueryParameter(s); guard with if (string.IsNullOrWhiteSpace(name)).
When building the parameters dictionary, filter out empty keys before passing it to GetUriWithQueryParameters.
If the name is optional, skip the call entirely rather than passing an empty string.
Trace where the empty name originates - often an unbound form field or a null-coalesced default.

Example fix

// before: name can be empty when the input is blank
var uri = nav.GetUriWithQueryParameter(userInput, value);

// after: guard before calling
if (!string.IsNullOrWhiteSpace(userInput))
    uri = nav.GetUriWithQueryParameter(userInput, value);

Defensive patterns

Strategy: validation

Validate before calling

if (string.IsNullOrEmpty(name)) throw new InvalidOperationException("Query parameter name must be non-empty.");

Type guard

static bool IsValidQueryName(string? name) => !string.IsNullOrWhiteSpace(name);

Try / catch

try { _ = new QueryParameterSource(name, values, formatter); }
catch (InvalidOperationException ex) when (ex.Message.Contains("empty query parameter names"))
{ /* skip or default the name */ }

Prevention

Filter empty keys out of any dictionary before calling GetUriWithQueryParameters.
Bind [SupplyParameterFromQuery] with an explicit Name when the property name is dynamic.
Add a guard at the form boundary: reject empty filter names before they propagate.

When it happens

Trigger: Calling navigationManager.GetUriWithQueryParameter(name, value) or GetUriWithQueryParameters(dict) where name (or a dictionary key) is null, empty, or whitespace-only. Reached when a caller passes a computed name that turned out empty (e.g. derived from a missing route parameter or an unset binding).

Common situations: Building a query parameter name from an empty input field; a dictionary produced from a query string round-trip that contains an empty key; an unset [SupplyParameterFromQuery] property whose name defaults to empty.

Related errors

AI-assisted analysis of dotnet/aspnetcore@3600ca084e (2026-08-11). Data as JSON: /api/errors/2006d0c7b281956d. Report an issue: GitHub.

Appendix: source

Thrown at src/Components/Components/src/NavigationManagerExtensions.cs:166

            _builder.Append(hash);
        }
    }

    // A utility for feeding a collection of parameter values into a QueryStringBuilder.
    // This is used when generating a querystring with a query parameter that has multiple values.
    private readonly struct QueryParameterSource<TValue>
    {
        private readonly IEnumerator<TValue?>? _enumerator;
        private readonly QueryParameterFormatter<TValue>? _formatter;

        public string EncodedName { get; }

        // Creates an empty instance to simulate a source without any elements.
        public QueryParameterSource(string name)
        {
            if (string.IsNullOrEmpty(name))
            {
                throw new InvalidOperationException(EmptyQueryParameterNameExceptionMessage);
            }

            EncodedName = Uri.EscapeDataString(name);

            _enumerator = default;
            _formatter = default;
        }

        public QueryParameterSource(string name, IEnumerable<TValue?> values, QueryParameterFormatter<TValue> formatter)
            : this(name)
        {
            _enumerator = values.GetEnumerator();
            _formatter = formatter;
        }

        public bool TryAppendNextParameter(ref QueryStringBuilder builder)
        {
            if (_enumerator is null || !_enumerator.MoveNext())

View on GitHub (pinned to 3600ca084e)