ErrLookup › Background articles › "Invalid query parameter" / "Failed to parse value of ...": fixing bad query string parameters across APIs

"Invalid query parameter" / "Failed to parse value of ...": fixing bad query string parameters across APIs

"Invalid query parameter" errors appear when an HTTP API query string value fails validation or parsing — things like "Order "asc " parameter is wrong, allowed: asc or desc", "The "updatedSince" query parameter must be a valid date.", "Failed to parse value of "diff_version" (...) as a uint64", or "invalid MinimumShouldMatch value". Developers hit these when a query parameter is misspelled, wrongly typed, badly formatted, or not one of the whitelisted values the server accepts, and the request is rejected before any real work happens.

Distilled from 98 documented records across 36 repositories.

Background

These errors come from the input-validation layer of an HTTP server or API client, at the very start of request handling. Before a handler touches storage or runs business logic, it parses the query string and checks each parameter's shape: is this a date, a boolean, an unsigned integer, a UUID, or one of a fixed set of enum values? When the check fails, the request is rejected with a 400-class response (or, in looser libraries, an exception that surfaces as a 500). The message usually echoes the offending parameter name and raw value — Nomad's "Failed to parse value of %q (%v) as a bool" names the field and the string received, Jaeger's "unable to parse param '%s': %w" wraps the lower-level parser's cause, and rqlite returns the parse error text verbatim as the 400 body. The reason this validation exists at all is safety: wallabag interpolates the order value directly into a Doctrine ORDER BY clause, KubeSphere parses filter keys that could carry injection-prone characters, and PentAGI refuses group fields that are not whitelisted in its SQL mapper. Whitelisting also guarantees the query is semantically meaningful — Jaeger rejects an inverted start-time range because the resulting filter can never match, and Shardeum rejects a non-positive limit because LIMIT ? with zero or negative values is meaningless.

What this looks like from the caller's side is an immediate failure with no partial work: Nomad's tty check rejects the exec request before an allocation is targeted, Weaviate's tenant-activity filter check returns 400 before the activity call runs, and LiteLLM validates sort_order before any Prisma query executes. The response is often more diagnostic than the message suggests — reading the wrapped cause, the echoed raw value, or the 400 body usually tells you exactly which parameter and which string arrived. Common silent culprits on the client side are unexpanded shell variables, values mangled by URL encoding (a trailing %0A newline, double-encoded quotes), locale-formatted dates instead of ISO 8601, and UI labels like "ascending" passed through instead of the API's "asc".

The family varies noticeably across libraries in three ways. First, strictness differs: wallabag's order and detail parameters accept case-insensitive values but its expect parameter is case-sensitive and its tag-feed sort lookup is case-sensitive with no trimming; LiteLLM lowercases sort_order before checking, while Nomad accepts the full set of Go strconv.ParseBool literals (1/t/T/TRUE/true/True and counterparts) but nothing else. Second, the HTTP surface differs: most return a clean 400, but wallabag's findEntries throws a plain \Exception that surfaces as a 500, Bagisto's reporting controllers abort with a bare Laravel 404 "Not Found", and sure's UUID filter errors render as 422 validation_failed. Third, the semantics of "missing" differ: Rocket.Chat's emoji-custom.list treats an empty updatedSince as absent, but its sync endpoints fail on a missing updatedSince because Date.parse(undefined) is NaN — the parameter is effectively required; Nomad treats absent boolean and uint64 parameters as nil and skips them entirely. Some validators check format only (sure's UUID checks reject malformed ids but accept well-formed UUIDs for nonexistent records, returning an empty list), while others check membership in a documented value set.

Common causes

What usually fixes it

Go deeper

Documented occurrences

…and 78 more across the corpus — use search.

Honest provenance: generated on 2026-09-04 from AI-assisted analysis of the linked records. See how records are made.