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 when a matcher that takes no expected value is invoked with one (index.ts:160-172). Matchers like toBeNull, toBeTruthy, toBeDefined call ensureNoExpected; supplying an argument is a usage error because those matchers compare against a fixed state, not a user-provided expected value.

Solutions

1. Remove the expected argument: expect(x).toBeNull().
2. If you meant to compare equality, use the right matcher: expect(x).toBe(null) for exact equality.
3. For custom matchers, only call ensureNoExpected when the matcher truly takes no expected value, and document it.
4. Add an ESLint rule banning arguments on zero-arg matchers (eslint-plugin-jest).

Example fix

// before
expect(user).toBeNull(null);
// after
expect(user).toBeNull();

// custom matcher authors
if (expected !== undefined) {
  throw new Error('This matcher must not receive an expected argument');
}
// test authors: just omit the argument
expect(x).toBeNull();

When it happens

Trigger: expect(x).toBeNull(null), expect(x).toBeTruthy(true), expect(x).toBeDefined(undefined), expect(x).toBeNaN(NaN), or writing a custom matcher that calls ensureNoExpected and then passing an argument from the test.

Common situations: Auto-completing matcher calls with a value out of habit; porting tests from expect(x).toBe(null) to toBeNull but keeping the argument; custom matchers that misuse ensureNoExpected; refactoring that left a stray argument.

Related errors

• value must be a number or bigint
• Expect takes at most one argument.
• path must be a string or array
• path must not be an empty array
• value must be a function

AI-assisted analysis of jestjs/jest@8e6d128e4a (2026-08-10). Data as JSON: /api/errors/3ced69e6e525414d. Report an issue: GitHub.

Appendix: 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 8e6d128e4a)