nodejs/node · error · TypeError

handler must be an object

Error message

handler must be an object

What it means

Thrown by the DecoratorHandler constructor when handler is not a non-null object. DecoratorHandler is a deprecated wrapper that forwards DispatchHandler callbacks to an inner handler; it needs an object to delegate to. The guard is typeof handler !== 'object' || handler === null. Note this throws TypeError, not InvalidArgumentError.

Source

Thrown at deps/undici/src/lib/handler/decorator-handler.js:16

'use strict'

const assert = require('node:assert')

/**
 * @deprecated
 */
module.exports = class DecoratorHandler {
  #handler
  #onCompleteCalled = false
  #onErrorCalled = false
  #onResponseStartCalled = false

  constructor (handler) {
    if (typeof handler !== 'object' || handler === null) {
      throw new TypeError('handler must be an object')
    }
    this.#handler = handler
  }

  onRequestStart (...args) {
    this.#handler.onRequestStart?.(...args)
  }

  onRequestUpgrade (...args) {
    assert(!this.#onCompleteCalled)
    assert(!this.#onErrorCalled)

    return this.#handler.onRequestUpgrade?.(...args)
  }

  onResponseStart (...args) {
    assert(!this.#onCompleteCalled)
    assert(!this.#onErrorCalled)

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Pass a non-null object implementing the DispatchHandler interface.
2. Since DecoratorHandler is deprecated, prefer a custom handler class or the modern interceptor APIs.
3. Default the inner handler to a no-op object { } if forwarding is optional.
4. Ensure the value is set on all code paths before constructing the decorator.

Example fix

// before
new DecoratorHandler()
// after
new DecoratorHandler({ onRequestStart() {}, onResponseEnd() {} })

if (handler == null || typeof handler !== 'object') {
  throw new TypeError('DecoratorHandler requires a non-null object handler')
}
new DecoratorHandler(handler)

function isHandlerObject(v) { return v != null && typeof v === 'object' }

When it happens

Trigger: Constructing new DecoratorHandler(undefined), new DecoratorHandler(null), or new DecoratorHandler('something'). Passing a function where an object was expected also fails because typeof function === 'function', not 'object'.

Common situations: Forgetting the inner handler argument; passing a callback in place of a handler object; migrating off the deprecated DecoratorHandler and mis-wiring arguments; partial refactor leaving handler unset on a branch.

Related errors

• callback must be a function
• expected headers to be an array
• invalid interceptor, expected function received ${typeof int
• invalid interceptor
• UND_ERR_INVALID_ARG

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