jestjs/jest · error · Error

this matcher must not have an expected argument

Error message

this matcher must not have an expected argument

What it means

Thrown by `ensureNoExpected` in jest-matcher-utils/index.ts:163 (via `matcherErrorMessage`) when `expected !== undefined`. This helper backs zero-argument matchers such as `toBeUndefined()`, `toBeDefined()`, `toBeNull()`, `toBeTruthy()`, `toBeFalsy()`, `toHaveBeenCalled()` — they take no expected value, so passing one is a usage error.

Source

Thrown at packages/jest-matcher-utils/src/index.ts:163

): string {
  const type = getType(value);
  const hasType =
    type !== 'null' && type !== 'undefined'
      ? `${name} has type:  ${type}\n`
      : '';
  const hasValue = `${name} has value: ${print(value)}`;
  return hasType + hasValue;
}

export const ensureNoExpected = (
  expected: unknown,
  matcherName: string,
  options?: MatcherHintOptions,
): void => {
  if (expected !== undefined) {
    // Prepend maybe not only for backward compatibility.
    const matcherString = (options ? '' : '[.not]') + matcherName;
    throw new Error(
      matcherErrorMessage(
        matcherHint(matcherString, undefined, '', options),
        // Because expected is omitted in hint above,
        // expected is black instead of green in message below.
        'this matcher must not have an expected argument',
        printWithType('Expected', expected, printExpected),
      ),
    );
  }
};

/**
 * Ensures that `actual` is of type `number | bigint`
 */
export const ensureActualIsNumber = (
  actual: unknown,
  matcherName: string,
  options?: MatcherHintOptions,

View on GitHub (pinned to f49721c78e)

Solutions

1. Drop the argument: `expect(x).toBeUndefined()`.
2. Use the right matcher: `toHaveBeenCalledTimes(n)` for counts, `toBe(undefined)` if you need a value comparison.
3. For custom matchers, call `ensureNoExpected` only in the no-arg branch and validate `expectedArgument` length yourself.

Example fix

// before
expect(value).toBeUndefined(null)
// after
expect(value).toBeUndefined()

// zero-argument matchers: do not pass a second arg
expect(value).toBeUndefined();
// if a value is required, use the value-comparing matcher:
expect(value).toBe(undefined);

const isZeroArgMatcher = (name: string): boolean =>
  ['toBeUndefined','toBeDefined','toBeNull','toBeTruthy','toBeFalsy','toHaveBeenCalled'].includes(name);

When it happens

Trigger: Writing `expect(x).toBeUndefined(null)`, `expect(fn).toHaveBeenCalled(2)`, or `expect(x).toBeTruthy('yes')`. Also hit by custom matchers that call `ensureNoExpected(expected, matcherName)` but receive an unexpected second argument.

Common situations: Confusing `toBeUndefined()` with `toBe(undefined)`; calling `toHaveBeenCalled()` with a count (use `toHaveBeenCalledTimes(n)` instead); custom matcher authored without checking argument count.

AI-assisted analysis of jestjs/jest@f49721c78e (2026-08-03). Data as JSON: /data/errors/3ced69e6e525414d.json. Report an issue: GitHub.