nodejs/node · error · InvalidArgumentError

Invalid dualStack. Must be a boolean

Error message

Invalid dualStack. Must be a boolean

What it means

Thrown by the DNS interceptor factory (`InvalidArgumentError`, code `UND_ERR_INVALID_ARG`) when `dualStack` is provided and is not a boolean. `dualStack` (default `true`) controls whether the interceptor issues parallel IPv4+IPv6 connect attempts (Happy Eyeballs) and races them; it must be a strict boolean because it gates branch logic that compares against `true`/`false`.

Source

Thrown at deps/undici/src/lib/interceptor/dns.js:488

  ) {
    throw new InvalidArgumentError(
      'Invalid maxItems. Must be a positive number and greater than zero'
    )
  }

  if (
    interceptorOpts?.affinity != null &&
    interceptorOpts?.affinity !== 4 &&
    interceptorOpts?.affinity !== 6
  ) {
    throw new InvalidArgumentError('Invalid affinity. Must be either 4 or 6')
  }

  if (
    interceptorOpts?.dualStack != null &&
    typeof interceptorOpts?.dualStack !== 'boolean'
  ) {
    throw new InvalidArgumentError('Invalid dualStack. Must be a boolean')
  }

  if (
    interceptorOpts?.lookup != null &&
    typeof interceptorOpts?.lookup !== 'function'
  ) {
    throw new InvalidArgumentError('Invalid lookup. Must be a function')
  }

  if (
    interceptorOpts?.pick != null &&
    typeof interceptorOpts?.pick !== 'function'
  ) {
    throw new InvalidArgumentError('Invalid pick. Must be a function')
  }

  if (
    interceptorOpts?.storage != null &&

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Pass a literal boolean: `dualStack: false`.
2. Coerce env strings explicitly: `dualStack: process.env.DUAL_STACK !== 'false'`.
3. If you only need family preference, leave `dualStack: true` and use `affinity` instead.

Example fix

// before
dns({ dualStack: process.env.DUAL_STACK })   // string 'false'
dns({ dualStack: 'true' })

// after
dns({ dualStack: false })
dns({ dualStack: process.env.DUAL_STACK !== 'false' })

function toBool(v, fallback = true) {
  if (v == null) return fallback
  if (typeof v === 'boolean') return v
  if (typeof v === 'string') return v.toLowerCase() !== 'false' && v !== '0'
  return Boolean(v)
}

function isBoolean(v) {
  return typeof v === 'boolean'
}

When it happens

Trigger: Passing `dualStack: 'true'` (string), `dualStack: 1`, `dualStack: 'yes'`, or `dualStack: undefined`-coerced-from-config. The guard is `dualStack != null && typeof !== 'boolean'`. Note `0`/`1` are numbers and fail.

Common situations: Reading the flag from an env var (`process.env.DUAL_STACK` is always a string); JSON config that serialized a truthy string; passing an integer from a checkbox. The default `true` masks the requirement until you try to force single-stack.

Related errors

• Invalid maxTTL. Must be a positive number
• Invalid maxItems. Must be a positive number and greater than
• Invalid affinity. Must be either 4 or 6
• UND_ERR_INVALID_ARG
• expected opts.methods to be an array, got ${typeof methods}

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