nodejs/node · error · InvalidArgumentError

UND_ERR_INVALID_ARG

UND_ERR_INVALID_ARG

Error message

invalid opts

What it means

Thrown by undici's RequestHandler constructor (the handler behind request()) when opts is null, undefined, or not an object. request() performs a single request and yields a one-shot response body. Code is UND_ERR_INVALID_ARG.

Source

Thrown at deps/undici/src/lib/api/api-request.js:14

'use strict'

const assert = require('node:assert')
const { AsyncResource } = require('node:async_hooks')
const { Readable } = require('./readable')
const { InvalidArgumentError, RequestAbortedError } = require('../core/errors')
const util = require('../core/util')

function noop () {}

class RequestHandler extends AsyncResource {
  constructor (opts, callback) {
    if (!opts || typeof opts !== 'object') {
      throw new InvalidArgumentError('invalid opts')
    }

    const { signal, method, opaque, body, onInfo, responseHeaders, highWaterMark } = opts

    try {
      if (typeof callback !== 'function') {
        throw new InvalidArgumentError('invalid callback')
      }

      if (highWaterMark != null && (!Number.isFinite(highWaterMark) || highWaterMark < 0)) {
        throw new InvalidArgumentError('invalid highWaterMark')
      }

      if (signal && typeof signal.on !== 'function' && typeof signal.addEventListener !== 'function') {
        throw new InvalidArgumentError('signal must be an EventEmitter or EventTarget')
      }

      if (method === 'CONNECT') {

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Pass an options object (even {}): request(url, {}, cb).
2. If using the promise form, request(url, opts) with opts defined.
3. Validate that opts is defined before calling.

Example fix

// before
await dispatcher.request(url, undefined)
// after
await dispatcher.request(url, {})

function withOpts(o) { return o && typeof o === 'object' ? o : {} }

function isOptsObject(o: unknown): o is Record<string, unknown> { return !!o && typeof o === 'object' }

try { await dispatcher.request(url, opts) }
catch (err) {
  if (err.code === 'UND_ERR_INVALID_ARG' && /invalid opts/.test(err.message)) throw new TypeError('request opts must be an object')
  throw err
}

When it happens

Trigger: Calling dispatcher.request(url, null, cb) or request(url, undefined, cb) — passing a non-object where the options object is required.

Common situations: Optional opts variable that resolved to undefined; passing the callback in the opts slot; reusing fetch-style two-arg signature.

Related errors

• UND_ERR_INVALID_ARG
• UND_ERR_INVALID_ARG
• UND_ERR_INVALID_ARG
• UND_ERR_INVALID_ARG
• UND_ERR_INVALID_ARG

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