jestjs/jest · error · Error

received value must be a number or bigint

Error message

received value must be a number or bigint

What it means

Thrown by ensureActualIsNumber in jest-matcher-utils when the RECEIVED (actual) value passed to a numeric matcher is not a 'number' or 'bigint'. Numeric matchers (toBeGreaterThan, toBeLessThan, toBeCloseTo, toBeGreaterThanOrEqual, toBeLessThanOrEqual) call ensureNumbers/ensureActualIsNumber to guard their arithmetic before comparing. The check uses typeof against both 'number' and 'bigint', so anything else (string, NaN, object, undefined, Date) trips it.

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 f49721c78e)

Solutions

1. Coerce the received value to a number before the matcher: expect(Number(actual)).toBeGreaterThan(5), or for dates use expect(actual.getTime()).toBeGreaterThan(...).
2. Confirm the value's runtime type with a quick console.log(typeof actual, actual) right before the expect; fix the upstream producer so it emits a number.
3. Switch to a matcher appropriate to the type, e.g. expect(actual).toBe('10') or expect(actual).toEqual(expect.any(String)) for strings, rather than forcing a numeric matcher.
4. For NaN specifically, use expect(Number.isNaN(actual)).toBe(true) instead of a numeric comparison.

Example fix

// before
expect(process.env.PORT).toBeGreaterThan(1024);
// after
expect(Number(process.env.PORT)).toBeGreaterThan(1024);

function assertNumericActual(actual: unknown, matcher: string) {
  if (typeof actual !== 'number' && typeof actual !== 'bigint') {
    throw new Error(`Cannot use ${matcher}: actual is ${typeof actual}`);
  }
}
assertNumericActual(port, 'toBeGreaterThan');
expect(port).toBeGreaterThan(1024);

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

if (isNumeric(actual)) {
  expect(actual).toBeGreaterThan(5);
} else {
  expect(Number(actual)).toBeGreaterThan(5);
}

When it happens

Trigger: Calling a numeric comparator with a non-numeric received value: expect('10').toBeGreaterThan(5); expect(NaN).toBeCloseTo(1); expect(undefined).toBeLessThan(2); expect({x:1}).toBeGreaterThanOrEqual(0). The matcher invokes ensureActualIsNumber(actual, ...) which throws because typeof actual is neither 'number' nor 'bigint'.

Common situations: Parsing a value from an API/env var as a string ('10' instead of 10); comparing a Date object directly instead of Date.now(); passing a BigInt-mixed-with-number scenario but with a non-numeric wrapper; a property that is undefined because the producer renamed/removed it; accidentally awaiting nothing or awaiting a non-promise that resolves to a string.

Related errors

• expected value must be a number or bigint
• expected value must be a non-negative integer
• @jest/diff-sequences: ${name} typeof ${typeof arg} is not a
• @jest/diff-sequences: ${name} typeof ${type} is not a functi
• any() expects to be passed a constructor function. Please pa

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