expressjs/express · error · TypeError

unknown value for query parser function: ' + val

Error message

unknown value for query parser function: ' + val

What it means

compileQueryParser (lib/utils.js:162-184) turns the 'query parser' setting into the function that populates req.query. Valid values are a function, true, false, 'simple' (Node's querystring.parse), or 'extended' (qs-style parsing); anything else hits the default case at line 180 and throws a TypeError when the setting is set.

Source

Thrown at lib/utils.js:180

exports.compileQueryParser = function compileQueryParser(val) {
  var fn;

  if (typeof val === 'function') {
    return val;
  }

  switch (val) {
    case true:
    case 'simple':
      fn = querystring.parse;
      break;
    case false:
      break;
    case 'extended':
      fn = parseExtendedQueryString;
      break;
    default:
      throw new TypeError('unknown value for query parser function: ' + val);
  }

  return fn;
}

/**
 * Compile "proxy trust" value to function.
 *
 * @param  {Boolean|String|Number|Array|Function} val
 * @return {Function}
 * @api private
 */

exports.compileTrust = function(val) {
  if (typeof val === 'function') return val;

  if (val === true) {
    // Support plain true/false

View on GitHub ↗ (pinned to a3714473fe)

Solutions

1. Use 'simple' or 'extended': app.set('query parser', 'extended').
2. If migrating from Express 4's 'qs' value, replace it with 'extended' (or pass qs.parse directly as a function for full control).
3. To disable query parsing entirely, pass false (the boolean, not the string).

Example fix

// before (Express 4 style)
app.set('query parser', 'qs');
// after (Express 5)
app.set('query parser', 'extended');

const VALID_QP = new Set([true, false, 'simple', 'extended']);
if (!VALID_QP.has(qpSetting) && typeof qpSetting !== 'function') {
  throw new TypeError(`invalid 'query parser' setting: ${JSON.stringify(qpSetting)}`);
}
app.set('query parser', qpSetting);

function isValidQueryParserSetting(val) {
  return val === true || val === false || val === 'simple' || val === 'extended' || typeof val === 'function';
}

try {
  app.set('query parser', config.queryParser);
} catch (err) {
  if (/unknown value for query parser/.test(err.message)) {
    // unsupported value from config — surface as a startup configuration error
  }
  throw err;
}

When it happens

Trigger: app.set('query parser', 'qs') — 'qs' was a valid alias historically but in this Express 5 code only 'simple'/'extended' strings are accepted; app.set('query parser', 'true') from an env var; any misspelling like 'extened'.

Common situations: Upgrading Express 4 apps that used app.set('query parser', 'qs') — Express 5 replaced that with 'extended' and changed the default to 'simple', so upgrade guides mention this exact setting; env-var-sourced config delivering strings; passing the qs module object instead of a parse function.

Related errors

• Invalid status code: ${JSON.stringify(code)}. Status code mu
• callback function required
• No default engine was specified and no extension was provide
• unknown value for etag function: ' + val
• path must be absolute or specify root to res.sendFile

AI-assisted analysis of expressjs/express@a3714473fe (2026-07-31). Data as JSON: /data/errors/9af288e79d430592.json. Report an issue: GitHub ↗.