jestjs/jest · error · Error

${RECEIVED_COLOR('received')} value must be a number or bigi

Error message

${RECEIVED_COLOR('received')} value must be a number or bigint

What it means

Thrown by ensureActualIsNumber in jest-matcher-utils when the received value is not a number or bigint (index.ts:183-193). Numeric matchers (toBeGreaterThan, toBeLessThan, toBeCloseTo, etc.) guard their inputs because they perform arithmetic comparisons; a non-numeric actual would produce NaN-driven nonsense results rather than a clear failure.

Source

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

        '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,
): void => {
  if (typeof actual !== 'number' && typeof actual !== 'bigint') {
    // Prepend maybe not only for backward compatibility.
    const matcherString = (options ? '' : '[.not]') + matcherName;
    throw new Error(
      matcherErrorMessage(
        matcherHint(matcherString, undefined, undefined, options),
        `${RECEIVED_COLOR('received')} value must be a number or bigint`,
        printWithType('Received', actual, printReceived),
      ),
    );
  }
};

/**
 * Ensures that `expected` is of type `number | bigint`
 */
export const ensureExpectedIsNumber = (
  expected: unknown,
  matcherName: string,
  options?: MatcherHintOptions,
): void => {
  if (typeof expected !== 'number' && typeof expected !== 'bigint') {

View on GitHub (pinned to 8e6d128e4a)

Solutions

1. Coerce or parse before asserting: expect(Number(x)).toBeGreaterThan(5) or expect(parseInt(x, 10)).toBeGreaterThan(5).
2. Fix the source so the value is actually a number: change the function return type and serialisation.
3. Add a type guard or earlier assertion: expect(typeof x).toBe('number').
4. If NaN is possible, guard explicitly: if (Number.isNaN(x)) throw ... or assert with expect(x).not.toBeNaN().

Example fix

// before
expect(getCountStr()).toBeGreaterThan(5); // returns '10'
// after
expect(Number(getCountStr())).toBeGreaterThan(5);

if (typeof actual !== 'number' && typeof actual !== 'bigint') {
  throw new TypeError('Numeric matcher requires a number or bigint actual');
}
expect(actual).toBeGreaterThan(expected);

const isNumeric = (v: unknown): v is number | bigint =>
  typeof v === 'number' || typeof v === 'bigint';

When it happens

Trigger: expect('10').toBeGreaterThan(5), expect(undefined).toBeCloseTo(1), expect(NaN).toBeLessThan(5), expect({val:1}).toBeGreaterThan(0), or expect('0x10').toBeGreaterThan(1) where a string is passed instead of a parsed number.

Common situations: Forgetting to parse numeric strings from env vars or DOM inputs; consuming an API that returns stringified numbers; undefined returned from a stubbed function; refactor that changed a return type from number to string; BigInt/Number mixing.

Related errors

• ${EXPECTED_COLOR('expected')} value must be a number
• ${RECEIVED_COLOR('received')} value must be a number
• this matcher must not have an expected argument
• ${EXPECTED_COLOR('expected')} value must be a function
• ${RECEIVED_COLOR('received')} value must not be null nor und

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