How to fix TypeError: Separator must be a string (querystring invalid separator) in Node.js

Node.jsBEGINNERLOWUpdated Dec 9, 2025· 106 views

This error occurs when passing a non-string value as the separator parameter to querystring.parse() or querystring.stringify(). The querystring module requires separator and assignment parameters to be strings, not null, undefined, numbers, or other types.

Quick fix

Fixes TypeError

const querystring = require('querystring');

// ❌ Wrong - undefined separator
const sep = undefined;
querystring.parse('foo=bar&baz=qux', sep); // TypeError

// ✅ Correct - use string or omit parameter
querystring.parse('foo=bar&baz=qux'); // Uses default '&'
querystring.parse('foo=bar&baz=qux', '&'); // Explicit string

// ✅ Correct - provide default if variable might be undefined
const customSep = sep || '&';
querystring.parse('foo=bar&baz=qux', customSep);
  1. Verify the separator parameter is a string
  2. Add type guards for dynamic separator values
  3. Use URLSearchParams for modern applications
  4. Check destructuring and default parameters
node.js — error
const querystring = require('querystring');
// ❌ Wrong - undefined separator
const sep = undefined;
querystring.parse('foo=bar&baz=qux', sep); // TypeError
// ✅ Correct - use string or omit parameter
querystring.parse('foo=bar&baz=qux'); // Uses default '&'
querystring.parse('foo=bar&baz=qux', '&'); // Explicit string
// ✅ Correct - provide default if variable might be undefined
const customSep = sep || '&';
querystring.parse('foo=bar&baz=qux', customSep);
TypeError: Separator must be a string (querystring invalid separator)

What this error means

The Node.js querystring module provides utilities for parsing and formatting URL query strings. The querystring.parse() method accepts optional parameters to customize how query strings are parsed: a separator parameter (sep) to delimit key-value pairs (defaults to '&'), and an assignment parameter (eq) to delimit keys from values (defaults to '='). This TypeError is thrown when you pass a non-string value to either the sep or eq parameters. The querystring module performs strict type checking on these parameters and will reject values like null, undefined, numbers, booleans, objects, or arrays. This validation ensures the parsing logic can reliably split the query string using string methods. The error typically surfaces when developers attempt to pass variables that might be undefined, use configuration objects that haven't been properly initialized, or accidentally pass the wrong type due to a logic error in their code.

Typical symptoms

  • Application crashes with TypeError when calling querystring.parse() or querystring.stringify()
  • Error occurs when using custom separators in query string parsing
  • TypeError is thrown before any query string processing begins
  • Error message specifically mentions "Separator must be a string"
  • Issue appears when separator parameters come from dynamic sources or configuration

Common causes

  1. Passing undefined or null as the sep or eq parameter instead of a string
  2. Using a variable for the separator that has not been initialized
  3. Accidentally passing a number or boolean where a string separator is expected
  4. Destructuring configuration objects with missing separator properties
  5. Type coercion issues when separator values come from external sources
  6. Forgetting to convert numeric or other types to strings before passing as separators

How to fix "TypeError: Separator must be a string (querystring invalid separator)"

1Verify the separator parameter is a string

Check that you're passing string values for both the separator and assignment parameters. The most common fix is to ensure variables are strings or use default values:

javascript
const querystring = require('querystring');

// ❌ Wrong - undefined separator
const sep = undefined;
querystring.parse('foo=bar&baz=qux', sep); // TypeError

// ✅ Correct - use string or omit parameter
querystring.parse('foo=bar&baz=qux'); // Uses default '&'
querystring.parse('foo=bar&baz=qux', '&'); // Explicit string

// ✅ Correct - provide default if variable might be undefined
const customSep = sep || '&';
querystring.parse('foo=bar&baz=qux', customSep);
2Add type guards for dynamic separator values

If separators come from configuration or external sources, validate them before use:

javascript
const querystring = require('querystring');

function parseQueryString(str, separator, assignment) {
  // Validate separator is a string
  const sep = typeof separator === 'string' ? separator : '&';
  const eq = typeof assignment === 'string' ? assignment : '=';

  return querystring.parse(str, sep, eq);
}

// Safe to use with any input types
parseQueryString('foo=bar&baz=qux', undefined, null); // Works
parseQueryString('foo:bar;baz:qux', ';', ':'); // Custom separators
3Use URLSearchParams for modern applications

For new code, consider using the built-in URLSearchParams API instead of the querystring module. URLSearchParams is the modern standard and doesn't require separator configuration:

javascript
// Modern approach with URLSearchParams
const params = new URLSearchParams('foo=bar&baz=qux');
console.log(params.get('foo')); // 'bar'
console.log(Object.fromEntries(params)); // { foo: 'bar', baz: 'qux' }

// Creating query strings
const newParams = new URLSearchParams({ foo: 'bar', baz: 'qux' });
console.log(newParams.toString()); // 'foo=bar&baz=qux'

Note: The querystring module has been deprecated in favor of URLSearchParams in modern Node.js versions.

4Check destructuring and default parameters

If separators come from options objects, ensure proper defaults are set:

javascript
const querystring = require('querystring');

// ❌ Wrong - properties might be undefined
function parseCustom(str, options) {
  return querystring.parse(str, options.sep, options.eq);
}
parseCustom('foo=bar', {}); // TypeError if sep is undefined

// ✅ Correct - use destructuring with defaults
function parseCustom(str, options = {}) {
  const { sep = '&', eq = '=' } = options;
  return querystring.parse(str, sep, eq);
}
parseCustom('foo=bar', {}); // Works
parseCustom('foo:bar', { sep: ';', eq: ':' }); // Custom separators

Advanced notes

Migration to URLSearchParams:
The querystring module is considered legacy and has been marked as deprecated in Node.js documentation. The URLSearchParams API provides better standards compliance and is available both in Node.js (via the 'url' module) and in browsers, making it ideal for isomorphic code.

TypeScript considerations:
When using TypeScript, you can enforce string types for separator parameters to catch these errors at compile time rather than runtime. Define function signatures with explicit string types for sep and eq parameters.

Custom separator validation:
While the querystring module accepts any string as a separator, be cautious with unusual separators. If the separator and assignment characters overlap or conflict, parsing results may be ambiguous. For example, using the same character for both sep and eq makes it impossible to distinguish between key-value pairs and pair separators.

Performance implications:
The querystring module uses optimized C++ bindings for parsing, making it faster than string manipulation in JavaScript. However, URLSearchParams provides comparable performance in modern Node.js versions while offering better encoding handling and standards compliance.

Frequently asked questions

What does "TypeError" mean?
js querystring module provides utilities for parsing and formatting URL query strings. parse() method accepts optional parameters to customize how query strings are parsed: a separator parameter (sep) to delimit key-value pairs (defaults to '&'), and an assignment parameter (eq) to delimit keys from values (defaults to '='). This TypeError is thrown when you pass a non-string value to either the sep or eq parameters.
How do I fix "TypeError"?
This error occurs when passing a non-string value as the separator parameter to querystring.parse() or querystring.stringify(). The querystring module requires separator and assignment parameters to be strings, not null, undefined, numbers, or other types.
What causes "TypeError"?
Passing undefined or null as the sep or eq parameter instead of a string Using a variable for the separator that has not been initialized Accidentally passing a number or boolean where a string separator is expected
Is the "TypeError" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading