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.
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.
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:
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);If separators come from configuration or external sources, validate them before use:
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 separatorsFor 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:
// 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.
If separators come from options objects, ensure proper defaults are set:
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 separatorsMigration 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.
Error: EMFILE: too many open files, watch
EMFILE: fs.watch() limit exceeded
Error: Listener already called (once event already fired)
EventEmitter listener already called with once()
Error: Middleware next() called multiple times (next() invoked twice)
Express middleware next() called multiple times
Error: Worker failed to initialize (worker startup error)
Worker failed to initialize in Node.js
Error: EMFILE: too many open files, open 'file.txt'
EMFILE: too many open files