nodejs/node · error · InvalidArgumentError

UND_ERR_INVALID_ARG

UND_ERR_INVALID_ARG

Error message

invalid opts

What it means

Thrown by undici's ConnectHandler constructor when the opts argument to connect() is null, undefined, or not an object. connect() is the low-level CONNECT-tunnel API (undici.connect). Code is UND_ERR_INVALID_ARG.

Source

Thrown at deps/undici/src/lib/api/api-connect.js:12

'use strict'

const assert = require('node:assert')
const { AsyncResource } = require('node:async_hooks')
const { InvalidArgumentError, SocketError } = require('../core/errors')
const util = require('../core/util')
const { addSignal, removeSignal } = require('./abort-signal')

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

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

    const { signal, opaque, responseHeaders } = opts

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

    super('UNDICI_CONNECT')

    this.opaque = opaque || null
    this.responseHeaders = responseHeaders || null
    this.callback = callback
    this.abort = null

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Pass a plain options object: connect({ path: 'example.com:443' }, handler).
2. Required fields go inside opts (e.g. path/destination, signal, opaque).
3. Check that the variable holding opts is actually defined and is an object before the call.

Example fix

// before
undici.connect('example.com:443', cb)
// after
undici.connect({ path: 'example.com:443' }, cb)

function assertConnectOpts(o) { if (!o || typeof o !== 'object') throw new TypeError('connect opts must be an object') }

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

undici.connect(opts, (err, data) => {
  if (err && err.code === 'UND_ERR_INVALID_ARG') console.error('bad connect opts:', err.message)
})

When it happens

Trigger: Calling undici.connect(null, cb), connect(undefined, cb), or connect('host:port', cb) — passing anything but a plain options object as the first argument.

Common situations: Assuming connect takes a URL string like fetch does; passing undefined because the opts variable was never assigned; reusing a fetch-style call signature.

Related errors

• UND_ERR_INVALID_ARG
• UND_ERR_SOCKET
• 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/49faab78f45482b0. Report an issue: GitHub.