{"record":{"id":"159e5c867b3f6b5d","repo":"dotnet/yarp","slug":"query-parameter-values-must-not-be-specified-when","errorCode":null,"errorMessage":"Query parameter values must not be specified when using '{nameof(QueryParameterMatchMode.Exists)}'.","messagePattern":"Query parameter values must not be specified when using '(.+?)'\\.","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/ReverseProxy/Routing/QueryParameterMatcher.cs","lineNumber":29,"sourceCode":"/// <summary>\n/// A request query parameter matcher used during routing.\n/// </summary>\ninternal sealed class QueryParameterMatcher\n{\n    /// <summary>\n    /// Creates a new instance.\n    /// </summary>\n    public QueryParameterMatcher(string name, IReadOnlyList<string>? values, QueryParameterMatchMode mode, bool isCaseSensitive)\n    {\n        ArgumentException.ThrowIfNullOrEmpty(name);\n        if (mode != QueryParameterMatchMode.Exists\n            && (values is null || values.Count == 0))\n        {\n            throw new ArgumentException(\"Query parameter values must have at least one value.\", nameof(values));\n        }\n        if (mode == QueryParameterMatchMode.Exists && values?.Count > 0)\n        {\n            throw new ArgumentException($\"Query parameter values must not be specified when using '{nameof(QueryParameterMatchMode.Exists)}'.\", nameof(values));\n        }\n        if (values is not null && values.Any(string.IsNullOrEmpty))\n        {\n            throw new ArgumentNullException(nameof(values), \"Query parameter values must not be empty.\");\n        }\n\n        Name = name;\n        Values = values?.ToArray() ?? Array.Empty<string>();\n        Mode = mode;\n        Comparison = isCaseSensitive ? StringComparison.Ordinal : StringComparison.OrdinalIgnoreCase;\n    }\n\n    /// <summary>\n    /// Name of the query parameter to look for.\n    /// </summary>\n    public string Name { get; }\n\n    /// <summary>","sourceCodeStart":11,"sourceCodeEnd":47,"githubUrl":"https://github.com/dotnet/yarp/blob/bd11867bee7df522e7fd3effb08a9c85fd616908/src/ReverseProxy/Routing/QueryParameterMatcher.cs#L11-L47","documentation":"Thrown by the QueryParameterMatcher constructor when Mode is `Exists` but `values` has more than zero entries. Exists mode only checks whether the query parameter is present, so supplying values is contradictory and almost always a config mistake.","triggerScenarios":"Constructing `new QueryParameterMatcher(name, values, QueryParameterMatchMode.Exists, ...)` with a non-empty `values` collection, or binding route config that sets both `mode: Exists` and a values list.","commonSituations":"Switched mode to Exists but left the values array populated. Config template that always emits a default values list.","solutions":["Remove the values entries for Exists-mode matchers.","If value matching is intended, change Mode to Exact/Prefix/Contains and keep the values.","Add a pre-construction assertion that Exists implies empty values."],"exampleFix":"// before\nnew QueryParameterMatcher(\"flag\", new[] { \"1\" }, QueryParameterMatchMode.Exists, false);\n// after\nnew QueryParameterMatcher(\"flag\", values: null, QueryParameterMatchMode.Exists, false);","handlingStrategy":"validation","validationCode":"if (mode == QueryParameterMatchMode.Exists && values?.Count > 0)\n    throw new InvalidOperationException(\"Exists mode cannot take values.\");","typeGuard":"static bool IsValidExistsMode(QueryParameterMatchMode mode, IReadOnlyList<string>? values) =>\n    mode != QueryParameterMatchMode.Exists || values is null || values.Count == 0;","tryCatchPattern":null,"preventionTips":["When switching a query match to Exists, clear the values list.","Add config validation that Exists implies empty values.","Avoid config templates that always inject a default values array."],"tags":["routing","query-match","argument-validation","yarp"],"backgroundTag":null,"analyzedSha":"bd11867bee7df522e7fd3effb08a9c85fd616908","analyzedAt":"2026-08-13T21:29:49.359Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}