skip to content

After an Express 4 to 5 upgrade, a search route's ?filter[status]=open stops filtering and middleware that rewrote req.query breaks; what changed?

level: seniorimportance: should knowfreq 40%

answer

  1. default parser changed
  2. simple versus extended
  3. a getter with no setter
  4. parsed again on every read

basics

~10 s

Express 5 changed the default 'query parser' from 'extended' to 'simple', which keeps filter[status] as a flat key, and made req.query a getter that re-parses the URL, so assignments to it throw or vanish.

solid answer

~40 s

Two Express 5 changes collide here. First, the `'query parser'` setting now defaults to `'simple'`, Node's query-string parser, so `?filter[status]=open` becomes `{ 'filter[status]': 'open' }` and `req.query.filter` is `undefined`; the route sees no filter and returns everything. `app.set('query parser', 'extended')` restores nested parsing through the `qs` library, or you pass your own parse function. Second, `req.query` is now a getter with no setter that parses the URL on every read. Assigning `req.query = parsed` throws a `TypeError` in strict-mode code and is silently ignored in sloppy code, and mutating `req.query.page` is lost because the next read builds a fresh object. Middleware should store its parsed result somewhere else instead.

code

javascript · 17 lines
javascript
const express = require('express');
const app = express();

// Express 5 default is 'simple': ?filter[status]=open -> { 'filter[status]': 'open' }
app.set('query parser', 'extended'); // -> { filter: { status: 'open' } }

app.use('/products', (req, res, next) => {
  // req.query = { ...req.query, page: 1 }; // TypeError in strict mode
  res.locals.query = { page: 1, ...req.query }; // store a copy instead
  next();
});

app.get('/products', (req, res) => {
  res.json({ filter: res.locals.query.filter, page: res.locals.query.page });
});

app.listen(3000);

go deeper

for a junior

Remember that Express 5 parses the query string with a 'simple' parser by default and that req.query cannot be reassigned.

for a middle

Explain the 'query parser' values, simple, extended, false or a function, and why the getter returns a new object on each read.

for a senior

Diagnose the silent widening when a nested filter disappears, find every req.query write in an upgraded codebase, and pick flat keys or an explicit parser.

for a principal

Set one query-string contract for the platform's APIs, flat or nested, and the parser limits that go with it, so upgrades and new services agree.

## The symptom A catalogue search accepts `GET /products?filter[status]=open&page=2`. On Express 4 the handler read `req.query.filter.status`. After the upgrade the route returns unfiltered results, and a normalising middleware that did `req.query = cleaned` now fails. Both trace back to two separate changes listed in the official Express 5 migration guide. ## Change 1: the default query parser is now `'simple'` Express picks the parser through the `'query parser'` application setting. The values it accepts: | Value | Parser | `?filter[status]=open` becomes | |---|---|---| | `'simple'` (Express 5 default) | Node's built-in query-string parser | `{ 'filter[status]': 'open' }` | | `'extended'` (Express 4 default) | the `qs` library | `{ filter: { status: 'open' } }` | | `false` | parsing disabled | an empty object | | a function | your own, called with the raw query string | whatever it returns | Under `'simple'` the brackets are just characters in the key name, so `req.query.filter` is `undefined` and code that treats a missing filter as "no filter" silently widens the result set. Repeated keys still work under `'simple'` (`?tag=a&tag=b` gives an array), so only bracket-nested shapes break. The fixes, in order of preference: 1. **Flatten the contract** to plain keys such as `?status=open`, which every parser reads the same way. 2. **Opt back in** with `app.set('query parser', 'extended')` on the app that serves the route. 3. **Supply a function** such as `(str) => qs.parse(str, { depth: 2 })` when you want nesting with tighter limits than the default `'extended'` parser. Nested parsing has a cost: it hands attacker-shaped objects and arrays to your code. Whatever parser you pick, validate the result. ## Change 2: `req.query` is a getter In Express 5, `req.query` is defined on the request prototype as a **getter with no setter**. Each read takes the URL's query string, runs the configured parser and returns a new object. That has three consequences: - **Assignment fails.** `req.query = cleaned` has nowhere to go. In strict-mode code, which includes every ES module, it throws `TypeError: Cannot set property query of #<IncomingMessage> which has only a getter`. In sloppy CommonJS it is silently ignored, which is worse because nothing reports it. - **Mutation is lost.** `req.query.page = 1` does not throw, but it writes to a throwaway object. The next `req.query` read parses the URL again and the change is gone. - **Reads are not shared.** `req.query === req.query` is `false`; two pieces of middleware never see the same object. The repair is to stop treating `req.query` as storage. A middleware that coerces or validates the query should put its result in its own place, such as a dedicated property on the request or `res.locals`, and handlers read that. How a team standardises that validation step belongs with the REST-wiring material; the Express fact is only that `req.query` cannot hold it. ## Arrays and custom parsers Array syntax splits the same way. With `?tag[]=a&tag[]=b`, the `'simple'` parser returns `{ 'tag[]': ['a', 'b'] }` while `'extended'` returns `{ tag: ['a', 'b'] }`. Code reading `req.query.tag` therefore sees `undefined` after the upgrade even though the repeated-key form `?tag=a&tag=b` still yields an array. A custom parser is any function that receives the complete raw query string and returns an object; Express calls it on every `req.query` read. That makes it the place to enforce limits: - cap nesting depth and array length if you accept nested shapes; - drop keys the API does not define; - keep it cheap, because a handler that reads `req.query` five times parses five times. ## Diagnosing it quickly - Log `JSON.stringify(req.query)` once: a key that literally contains `[` shows the `'simple'` parser at work. - Check `app.get('query parser')` on the app (or sub-app) that handles the route, because each Express app carries its own settings. - Search the codebase for `req.query =` and `req.query.` on the left of an assignment; each hit is either a crash or a silent no-op after the upgrade. - Run tests from an ES module or a `'use strict'` file, so a leftover `req.query =` assignment throws instead of being silently ignored. - The upgrade codemods from the Express team rewrite removed method signatures, but a query contract is behaviour, so tests that send real nested queries are what catch it.

  • Why can't middleware fix this by setting req.query.page = 1 before the handler?
    In Express 5 every read of `req.query` runs the parser again and returns a new object. The write lands on the object that one read produced, and the handler's later read gets a fresh parse without it. Nothing throws, so the bug is silent; store the normalised value elsewhere and read it from there.
  • What does setting 'query parser' to false do in Express 5?
    It disables query parsing: `req.query` returns an empty object no matter what the URL carries. The raw string is still in `req.url`, so a route that needs it can parse it itself. Teams use it when no route reads query parameters and they want none of that input reaching handlers.

req.query is like a receipt the till reprints every time you ask for it: writing on one copy changes nothing on the next print, and the till decides how the line items are grouped.

  • Express 5 still parses nested bracket keys like filter[status] by default
  • Assigning a new object to req.query works as it did in Express 4
  • Changing req.query.page in middleware is visible to the next handler
  • The 'simple' parser cannot produce arrays for repeated keys
  • Switching to 'extended' is free of any security consideration

Assumes Express 5: the 'query parser' default moved from 'extended' to 'simple' and req.query became a getter; Express 4 let middleware assign it.