nodejs/node · error · InvalidArgumentError

Invalid maxItems. Must be a positive number and greater than

Error message

Invalid maxItems. Must be a positive number and greater than zero

What it means

Thrown by the DNS interceptor factory (`InvalidArgumentError`, code `UND_ERR_INVALID_ARG`) when `maxItems` is provided and is either not a number or is less than 1. `maxItems` bounds the size of the in-process DNS cache so it cannot grow unbounded over a long-running process; at least one slot is required. Unlike `maxTTL`, zero is explicitly rejected here (`< 1`).

Source

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

        break
    }
  }
}

module.exports = interceptorOpts => {
  if (
    interceptorOpts?.maxTTL != null &&
    (typeof interceptorOpts?.maxTTL !== 'number' || interceptorOpts?.maxTTL < 0)
  ) {
    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')
  }

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Pass a positive integer ≥1, e.g. `maxItems: 100`.
2. To effectively disable caching, set `maxTTL: 0` instead of shrinking `maxItems` to 0.
3. Coerce and validate env-derived values: `Number.isInteger(v) && v >= 1`.

Example fix

// before
dns({ maxItems: 0 })
dns({ maxItems: process.env.DNS_MAX })

// after
dns({ maxItems: 100 })
dns({ maxItems: Number(process.env.DNS_MAX) })

function validateMaxItems(v) {
  if (v == null) return undefined
  if (typeof v !== 'number' || v < 1 || !Number.isInteger(v)) {
    throw new Error('maxItems must be a positive integer')
  }
  return v
}

function isPositiveInteger(v) {
  return typeof v === 'number' && Number.isInteger(v) && v >= 1
}

When it happens

Trigger: Passing `maxItems: 0`, a negative number, a non-number, or a fractional value intending a cap. The check is `typeof !== 'number' || < 1`. Floats ≥1 technically pass (the cache keying tolerates them) but an integer is intended.

Common situations: Setting `maxItems: 0` to 'disable' the cache (it errors, not disables); reading the value from config as a string; passing a value tuned for a different cache library that allowed zero.

Related errors

• Invalid maxTTL. Must be a positive number
• Invalid affinity. Must be either 4 or 6
• Invalid dualStack. Must be a boolean
• UND_ERR_INVALID_ARG
• expected ${name} to be an array or undefined, got ${typeof o

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