nodejs/node · critical · InvalidArgumentError

UND_ERR_INVALID_ARG

UND_ERR_INVALID_ARG

Error message

http module not available or http.maxHeaderSize invalid

What it means

Thrown by getDefaultNodeMaxHeaderSize in client.js when Node's built-in http module is missing OR http.maxHeaderSize is not a positive integer. The Client reads Node's default header-size limit lazily; if the host environment is non-conformant (a stripped Node build, a broken bundler, or http.maxHeaderSize manually set to a bad value), undici cannot derive a safe default and refuses to construct rather than silently use an unsafe limit.

Source

Thrown at deps/undici/src/lib/dispatcher/client.js:69

  kMaxResponseSize,
  kOnError,
  kHTTPContext,
  kMaxConcurrentStreams,
  kHostAuthority,
  kResume,
  kHTTP2Options
} = require('../core/symbols.js')
const connectH1 = require('./client-h1.js')
const connectH2 = require('./client-h2.js')

const kClosedResolve = Symbol('kClosedResolve')

const getDefaultNodeMaxHeaderSize = http &&
  http.maxHeaderSize &&
  Number.isInteger(http.maxHeaderSize) &&
  http.maxHeaderSize > 0
  ? () => http.maxHeaderSize
  : () => { throw new InvalidArgumentError('http module not available or http.maxHeaderSize invalid') }

const noop = () => { }

function getPipelining (client) {
  return client[kPipelining] ?? client[kHTTPContext]?.defaultPipelining ?? 1
}

let h2NamespaceOptsWarning = false
function emitH2OptionsNamespaceWarning (optName) {
  if (h2NamespaceOptsWarning === true) return

  process.emitWarning(`Use h2Options.${optName} instead. ${optName} for H2 will be deprecated in future major.`, {
    code: 'UNDICI-H2-OPTIONS'
  })
  h2NamespaceOptsWarning = true
}

// Protocol-aware dispatch ceiling. h1 RFC7230 pipelining is unrelated to h2

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Run on a standard Node.js release where require('http').maxHeaderSize is a positive integer.
2. Remove any code that sets http.maxHeaderSize to a non-positive or non-integer value.
3. If you must override the limit, pass maxHeaderSize explicitly in the Client options (a positive integer).
4. In bundlers, mark 'http' as external or use a runtime that provides Node core.

Example fix

// before — somewhere at startup
require('http').maxHeaderSize = 0
const client = new Client(origin) // throws
// after — do not zero out the default, or pass an explicit value
const client = new Client(origin, { maxHeaderSize: 16384 })

const http = require('http')
function assertHttpEnv() {
  if (!http || !Number.isInteger(http.maxHeaderSize) || http.maxHeaderSize <= 0) {
    throw new Error('Node http module unavailable or http.maxHeaderSize invalid')
  }
}
assertHttpEnv()
const client = new Client(origin, { maxHeaderSize: 16384 }) // explicit, env-independent

function httpEnvOk() {
  const http = require('http')
  return !!http && Number.isInteger(http.maxHeaderSize) && http.maxHeaderSize > 0
}

When it happens

Trigger: Running undici in an environment where require('http') is undefined or where http.maxHeaderSize was set to 0 / a negative / a non-integer before the Client is constructed.

Common situations: Bundling undici for a non-Node runtime (browser/electron renderer without Node core); a polyfill that omits maxHeaderSize; a startup script that sets http.maxHeaderSize = 0; a corrupted Node installation.

Related errors

• UND_ERR_SOCKET
• Add ${this.npm.globalBin} to your $PATH
• Install git and ensure it's in your PATH.
• UND_ERR_INVALID_ARG
• UND_ERR_INVALID_ARG

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