nodejs/node · error · InvalidArgumentError

UND_ERR_INVALID_ARG

UND_ERR_INVALID_ARG

Error message

Argument opts.agent must implement Agent

What it means

Thrown by the MockClient constructor when opts is missing, opts.agent is missing, or opts.agent.dispatch is not a function. MockClient extends Client and needs the parent MockAgent to delegate unmatched dispatches and share state, so the agent must look like an Agent (duck-typed on dispatch).

Source

Thrown at deps/undici/src/lib/mock/mock-client.js:26

  kMockAgent,
  kClose,
  kOriginalClose,
  kOrigin,
  kOriginalDispatch,
  kConnected,
  kIgnoreTrailingSlash
} = require('./mock-symbols')
const { MockInterceptor } = require('./mock-interceptor')
const Symbols = require('../core/symbols')
const { InvalidArgumentError } = require('../core/errors')

/**
 * MockClient provides an API that extends the Client to influence the mockDispatches.
 */
class MockClient extends Client {
  constructor (origin, opts) {
    if (!opts || !opts.agent || typeof opts.agent.dispatch !== 'function') {
      throw new InvalidArgumentError('Argument opts.agent must implement Agent')
    }

    super(origin, opts)

    this[kMockAgent] = opts.agent
    this[kOrigin] = origin
    this[kIgnoreTrailingSlash] = opts.ignoreTrailingSlash ?? false
    this[kDispatches] = []
    this[kConnected] = 1
    this[kOriginalDispatch] = this.dispatch
    this[kOriginalClose] = this.close.bind(this)

    this.dispatch = buildMockDispatch.call(this)
    this.close = this[kClose]
  }

  get [Symbols.kConnected] () {
    return this[kConnected]

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Obtain a MockClient through the MockAgent: const client = mockAgent.get('http://localhost:3000').
2. If constructing manually, pass the MockAgent: new MockClient(origin, { agent: mockAgent }).
3. Ensure the passed agent is a real MockAgent instance (it exposes dispatch).

Example fix

// before
const client = new MockClient('http://localhost:3000')

// after
const mockAgent = new MockAgent()
const client = mockAgent.get('http://localhost:3000')
// or
const client = new MockClient('http://localhost:3000', { agent: mockAgent })

function getMockClient(mockAgent, origin) {
  if (!mockAgent || typeof mockAgent.dispatch !== 'function') {
    throw new TypeError('Provide a MockAgent instance');
  }
  return mockAgent.get(origin);
}

function isAgentLike(v) {
  return v != null && typeof v.dispatch === 'function';
}

When it happens

Trigger: Constructing `new MockClient(origin)` with no opts, with opts that omit agent, or passing a plain object/custom agent that has no dispatch method. Most commonly hit when instantiating MockClient directly instead of obtaining it via mockAgent.get(origin).

Common situations: Manually new-ing MockClient for a test instead of using MockAgent.get(); passing a real undici Agent/Pool where a MockAgent was expected; refactoring that drops the agent option.

Related errors

• UND_ERR_INVALID_ARG
• UND_ERR_INVALID_ARG
• SqliteCacheStore options must be an object
• UND_ERR_INVALID_ARG
• UND_ERR_INVALID_ARG

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