nodejs/node · error · InvalidArgumentError

UND_ERR_INVALID_ARG

UND_ERR_INVALID_ARG

Error message

invalid opts

What it means

Thrown by undici's PipelineHandler constructor when the opts argument to pipeline() is null, undefined, or not an object. pipeline() streams a request body and response body through a user handler. Code is UND_ERR_INVALID_ARG.

Source

Thrown at deps/undici/src/lib/api/api-pipeline.js:71

  }

  _read () {
    this[kResume]()
  }

  _destroy (err, callback) {
    if (!err && !this._readableState.endEmitted) {
      err = new RequestAbortedError()
    }

    callback(err)
  }
}

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

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

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

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

    if (method === 'CONNECT') {
      throw new InvalidArgumentError('invalid method')
    }

    if (onInfo && typeof onInfo !== 'function') {
      throw new InvalidArgumentError('invalid onInfo callback')

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Pass a plain options object even if empty: pipeline(url, {}, handler).
2. Verify opts is built and defined before the call.
3. Remember pipeline signature is (url, opts, handler) — three args.

Example fix

// before
undici.pipeline(url, undefined, handler)
// after
undici.pipeline(url, {}, handler)

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

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

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

When it happens

Trigger: Calling undici.pipeline(url, null, handler) or pipeline(url, undefined, handler) — passing a non-object where the options object is required.

Common situations: Omitting opts but keeping the position (call signature confusion); passing a string/object that is actually the handler; conditionally building opts that resolved to undefined.

Related errors

• UND_ERR_INVALID_RETURN_VALUE
• 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/832f85661ef4066b. Report an issue: GitHub.