nodejs/node · error · InvalidArgumentError

invalid connections

Error message

invalid connections

What it means

Thrown by the RoundRobinPool constructor when the connections option is present but not finite (NaN/Infinity) or negative. RoundRobinPool spreads requests across N upstream clients; an invalid connections count would break the round-robin index arithmetic. The guard is identical to Pool's: connections != null && (!Number.isFinite(connections) || connections < 0).

Source

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

}

class RoundRobinPool extends PoolBase {
  constructor (origin, {
    connections,
    factory = defaultFactory,
    connect,
    connectTimeout,
    tls,
    maxCachedSessions,
    socketPath,
    autoSelectFamily,
    autoSelectFamilyAttemptTimeout,
    allowH2,
    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,
        socketPath,
        timeout: connectTimeout,
        ...(typeof autoSelectFamily === 'boolean' ? { autoSelectFamily, autoSelectFamilyAttemptTimeout } : undefined),

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Set connections to a non-negative finite integer, or pass 0 / omit it for auto-sizing.
2. Coerce numeric config with Number.isFinite checks before passing.
3. Use 0 (not Infinity) when you want the pool to size itself.
4. Validate the value in a shared config helper used by both Pool and RoundRobinPool.

Example fix

// before
new RoundRobinPool(url, { connections: Infinity })
// after
new RoundRobinPool(url, { connections: 10 })

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 RoundRobinPool(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, a non-number, or a numeric string that was not parsed. 0 is allowed (Pool treats it as auto-sizing).

Common situations: Env-driven config parsed as a string; arithmetic yielding NaN; using Infinity to mean 'unlimited'; sharing a config object between Pool and RoundRobinPool where the value was tuned for one and is invalid for the other.

Related errors

• UND_ERR_INVALID_ARG
• factory must be a function.
• connect must be a function or an object
• UND_ERR_INVALID_ARG
• UND_ERR_INVALID_ARG

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