What causes "Argument dispatcher must implement dispatch" in nodejs/node?

Pass an undici dispatcher instance (Client, Pool, Agent) which implements dispatch.

nodejs/node · error · InvalidArgumentError

UND_ERR_INVALID_ARG

UND_ERR_INVALID_ARG

Error message

Argument dispatcher must implement dispatch

What it means

InvalidArgumentError (UND_ERR_INVALID_ARG) thrown by the Dispatcher1Wrapper constructor when the supplied dispatcher is null/undefined or lacks a dispatch function. Dispatcher1Wrapper adapts a v1 dispatcher/handler surface for legacy consumers, so it requires a real dispatcher object exposing dispatch().

Source

Thrown at deps/undici/src/lib/dispatcher/dispatcher1-wrapper.js:70

  }

  onRequestSent () {
    this.#handler.onRequestSent?.()
  }

  onResponseStarted () {
    this.#handler.onResponseStarted?.()
  }
}

class Dispatcher1Wrapper extends Dispatcher {
  #dispatcher

  constructor (dispatcher) {
    super()

    if (!dispatcher || typeof dispatcher.dispatch !== 'function') {
      throw new InvalidArgumentError('Argument dispatcher must implement dispatch')
    }

    this.#dispatcher = dispatcher
  }

  static wrapHandler (handler) {
    if (!handler || typeof handler !== 'object') {
      throw new InvalidArgumentError('handler must be an object')
    }

    if (typeof handler.onRequestStart === 'function') {
      return handler
    }

    return new LegacyHandlerWrapper(handler)
  }

  dispatch (opts, handler) {

View on GitHub (pinned to 1b2de5e052)

Solutions

Pass an undici dispatcher instance (Client, Pool, Agent) which implements dispatch.
If wrapping a custom object, ensure it exposes a dispatch(opts, handler) function.
Check the argument is non-null and has typeof .dispatch === 'function' before construction.

Example fix

// before
new Dispatcher1Wrapper({ handle() {} })
// after
const { Agent } = require('undici')
new Dispatcher1Wrapper(new Agent())

Defensive patterns

Strategy: type-guard

Validate before calling

function wrapDispatcher1(dispatcher) {
  if (!dispatcher || typeof dispatcher.dispatch !== 'function') {
    throw new TypeError('dispatcher must implement dispatch(opts, handler)');
  }
  return new Dispatcher1Wrapper(dispatcher);
}

Type guard

!!dispatcher && typeof dispatcher.dispatch === 'function'

Prevention

Pass a real undici dispatcher (Client/Pool/Agent) to Dispatcher1Wrapper.
Do not pass handler objects or plain config objects where a dispatcher is expected.
Validate the dispatch method exists before wrapping.

When it happens

Trigger: Constructing `new Dispatcher1Wrapper(null)`, `new Dispatcher1Wrapper({})`, or `new Dispatcher1Wrapper({ dispatch: 'no' })`. Fires at dispatcher1-wrapper.js:69-70.

Common situations: Passing a plain handler object where the dispatcher is expected; passing an Agent/Client that failed to construct (so undefined); mixing up the constructor argument order; wrapping an object that mimics a dispatcher but names its method differently.

Related errors

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