nodejs/node · error · InvalidArgumentError

UND_ERR_INVALID_ARG

UND_ERR_INVALID_ARG

Error message

invalid connections

What it means

Thrown by the Pool constructor when the connections option is present but either not finite (NaN/Infinity) or negative. Pool needs a non-negative number of upstream client connections to manage; an invalid value would break the connection-counting loop used for distribution.

Source

Thrown at deps/undici/src/lib/dispatcher/pool.js:45

class Pool extends PoolBase {
  constructor (origin, {
    connections,
    factory = defaultFactory,
    connect,
    connectTimeout,
    tls,
    maxCachedSessions,
    socketPath,
    autoSelectFamily,
    autoSelectFamilyAttemptTimeout,
    allowH2,
    useH2c,
    clientTtl,
    ...options
  } = {}) {
    if (connections != null && (!Number.isFinite(connections) || connections < 0)) {
      throw new InvalidArgumentError('invalid connections')
    }

    if (typeof factory !== 'function') {
      throw new InvalidArgumentError('factory must be a function.')
    }

    if (connect != null && typeof connect !== 'function' && typeof connect !== 'object') {
      throw new InvalidArgumentError('connect must be a function or an object')
    }

    if (typeof connect !== 'function') {
      connect = buildConnector({
        ...tls,
        maxCachedSessions,
        allowH2,
        useH2c,
        socketPath,
        timeout: connectTimeout,

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Set connections to a non-negative finite integer, or use 0 to let Pool size automatically.
2. Coerce and validate numeric config: Number.isFinite(x) && x >= 0 before passing.
3. If you meant unlimited, pass 0 rather than Infinity.
4. Check for typos in the option key name.

Example fix

// before
new Pool(url, { connections: parseInt(process.env.POOL_SIZE) }) // NaN when unset
// after
const c = Number(process.env.POOL_SIZE)
new Pool(url, { connections: Number.isFinite(c) && c >= 0 ? c : undefined })

function resolveConnections(v) {
  if (v == null) return undefined
  if (!Number.isFinite(v) || v < 0) throw new Error('connections must be a non-negative finite number')
  return v
}
new Pool(url, { connections: resolveConnections(cfg.connections) })

function isValidConnections(v) { return v == null || (Number.isFinite(v) && v >= 0) }

When it happens

Trigger: Passing connections: -1, NaN, Infinity, or a non-number. The guard connections != null && (!Number.isFinite(connections) || connections < 0) lets 0 through (which Pool interprets as auto/infinite). Floats like 1.5 pass Number.isFinite but are usually unintended.

Common situations: Env var or config string not coerced to a number; arithmetic that yields NaN (e.g. undefined - 1); typo passing connectionCount under the wrong key; infinity used to mean 'unlimited' (use 0 instead).

Related errors

• invalid connections
• UND_ERR_INVALID_ARG
• UND_ERR_INVALID_ARG
• Proxy opts.clientFactory must be a function.
• opts.auth cannot be used in combination with opts.token

AI-assisted analysis of nodejs/node@1b2de5e052 (2026-08-13). Data as JSON: /api/errors/47d52170429c1085. Report an issue: GitHub.