nodejs/node · error · MockNotMatchedError

UND_MOCK_ERR_MOCK_NOT_MATCHED

UND_MOCK_ERR_MOCK_NOT_MATCHED

Error message

Mock dispatch not matched for path '${resolvedPath}'

What it means

Thrown by getMockDispatch when, after filtering out consumed dispatches and applying path matching, no registered mock dispatch's path matches the request's resolved path. This is the first matching stage in the mock resolution pipeline; path is matched via matchValue (string equality, RegExp test, or predicate function), with optional trailing-slash normalization.

Source

Thrown at deps/undici/src/lib/mock/mock-utils.js:186

  }
}

function getMockDispatch (mockDispatches, key) {
  const basePath = key.query ? serializePathWithQuery(key.path, key.query) : key.path
  const resolvedPath = typeof basePath === 'string' ? safeUrl(basePath) : basePath

  const resolvedPathWithoutTrailingSlash = removeTrailingSlash(resolvedPath)

  // Match path
  let matchedMockDispatches = mockDispatches
    .filter(({ consumed }) => !consumed)
    .filter(({ path, ignoreTrailingSlash }) => {
      return ignoreTrailingSlash
        ? matchValue(removeTrailingSlash(safeUrl(path)), resolvedPathWithoutTrailingSlash)
        : matchValue(safeUrl(path), resolvedPath)
    })
  if (matchedMockDispatches.length === 0) {
    throw new MockNotMatchedError(`Mock dispatch not matched for path '${resolvedPath}'`)
  }

  // Match method
  matchedMockDispatches = matchedMockDispatches.filter(({ method }) => matchValue(method, key.method))
  if (matchedMockDispatches.length === 0) {
    throw new MockNotMatchedError(`Mock dispatch not matched for method '${key.method}' on path '${resolvedPath}'`)
  }

  // Match body
  matchedMockDispatches = matchedMockDispatches.filter(({ body }) => typeof body !== 'undefined' ? matchValue(body, key.body) : true)
  if (matchedMockDispatches.length === 0) {
    throw new MockNotMatchedError(`Mock dispatch not matched for body '${key.body}' on path '${resolvedPath}'`)
  }

  // Match headers
  matchedMockDispatches = matchedMockDispatches.filter((mockDispatch) => matchHeaders(mockDispatch, key.headers))
  if (matchedMockDispatches.length === 0) {
    const headers = typeof key.headers === 'object' ? JSON.stringify(key.headers) : key.headers

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Register an intercept for the exact path the request uses: intercept({ path: '/users' }).
2. If the request has query params, pass opts.query to intercept() or include them in the path.
3. Increase repeat count with .times(N) or .persist() if dispatches are being consumed.
4. Set ignoreTrailingSlash: true on the agent/interceptor if '/users' vs '/users/' is the issue.
5. Verify mockAgent.disableNetConnect() / enableNetConnect is set so unmatched requests fail loudly rather than hitting the network.

Example fix

// before
mockAgent.disableNetConnect()
client.intercept({ path: '/users', method: 'GET' }).reply(200)
await request('/user') // typo, no match

// after
client.intercept({ path: '/user', method: 'GET' }).reply(200)
await request('/user')
// or fix the request to '/users'

function ensureInterceptForPath(mockClient, path, method = 'GET') {
  const dispatches = mockClient[kDispatches] || [];
  const exists = dispatches.some(d => !d.consumed && matchPath(d.path, path));
  if (!exists) {
    mockClient.intercept({ path, method }).reply(200);
  }
}

function isPathRegistered(dispatches, path) {
  return dispatches.some(d => !d.consumed && (d.path === path || (d.path instanceof RegExp && d.path.test(path))));
}

try {
  await client.request({ path, method });
} catch (e) {
  if (e.code === 'UND_MOCK_ERR_MOCK_NOT_MATCHED' && /not matched for path/.test(e.message)) {
    // register the missing intercept, then retry
    client.intercept({ path, method }).reply(200);
    await client.request({ path, method });
  } else throw e;
}

When it happens

Trigger: A request is dispatched (via client/pool/fetch under a MockAgent) whose URL path does not match any intercept() registration. Examples: requesting '/user' when only '/users' is registered; requesting '/users?id=1' when the path was registered without considering query normalization; all dispatches for that path already consumed; the mock agent is active but no intercept was added.

Common situations: Typo in the intercepted path; path includes query string that wasn't in the registration (use opts.query); all repeat-count consumed; trailing slash mismatch (enable ignoreTrailingSlash); forgot to disable net connect so real requests bypass mocks; the MockAgent was not enabled.

Related errors

• UND_ERR_INVALID_ARG
• UND_ERR
• 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/cb837d3a6ba4848f. Report an issue: GitHub.