nodejs/node · error · InvalidArgumentError

Invalid affinity. Must be either 4 or 6

Error message

Invalid affinity. Must be either 4 or 6

What it means

Thrown by the DNS interceptor factory (`InvalidArgumentError`, code `UND_ERR_INVALID_ARG`) when `affinity` is provided and is neither `4` (IPv4) nor `6` (IPv6). `affinity` biases connection attempts toward one address family in dual-stack setups so the connect race prefers the desired family. Only the two literal integers are accepted — no strings, booleans, or other numbers.

Source

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

    throw new InvalidArgumentError('Invalid maxTTL. Must be a positive number')
  }

  if (
    interceptorOpts?.maxItems != null &&
    (typeof interceptorOpts?.maxItems !== 'number' ||
      interceptorOpts?.maxItems < 1)
  ) {
    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 &&

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Pass either `affinity: 4` or `affinity: 6` as a literal integer.
2. If the value comes from config, coerce: `Number(affinity) === 4 ? 4 : Number(affinity) === 6 ? 6 : undefined`.
3. If you have no preference, omit `affinity` entirely — the interceptor picks a sensible default based on `dualStack`.

Example fix

// before
dns({ affinity: '4' })
dns({ affinity: process.env.IP_FAMILY })

// after
dns({ affinity: 4 })
// or omit it:
dns({ dualStack: true })

function validateAffinity(v) {
  if (v == null) return undefined
  const n = Number(v)
  if (n !== 4 && n !== 6) throw new Error('affinity must be 4 or 6')
  return n
}

function isAffinity(v) {
  return v === 4 || v === 6
}

When it happens

Trigger: Passing `affinity: '4'` (string), `affinity: 0`, `affinity: 'ipv4'`, `affinity: true`, or any number other than 4 or 6. The guard is `affinity != null && affinity !== 4 && affinity !== 6`.

Common situations: Loading `affinity` from env/config as a string; using an enum-like string token from another library; passing a stringified family from JSON config. When `dualStack` is false the default affinity becomes 4, so omitting the option is usually what you want.

Related errors

• Invalid maxTTL. Must be a positive number
• Invalid maxItems. Must be a positive number and greater than
• Invalid dualStack. Must be a boolean
• 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/42874bbdcdaefed3. Report an issue: GitHub.