jestjs/jest · error · Error

${EXPECTED_COLOR('expected')} value must be a number or bigi

Error message

${EXPECTED_COLOR('expected')} value must be a number or bigint

What it means

Thrown by ensureExpectedIsNumber in jest-matcher-utils, a guard invoked by Jest's numeric comparison matchers (toBeGreaterThan,toBeLessThan,toBeGreaterThanOrEqual,toBeLessThanOrEqual,toBeCloseTo). It validates the `expected` argument is `number` or `bigint` before performing the comparison so the matcher fails fast with a clear message instead of producing a misleading pass/fail from coercion.

Source

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

        `${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') {
    // Prepend maybe not only for backward compatibility.
    const matcherString = (options ? '' : '[.not]') + matcherName;
    throw new Error(
      matcherErrorMessage(
        matcherHint(matcherString, undefined, undefined, options),
        `${EXPECTED_COLOR('expected')} value must be a number or bigint`,
        printWithType('Expected', expected, printExpected),
      ),
    );
  }
};

/**
 * Ensures that `actual` & `expected` are of type `number | bigint`
 */
export const ensureNumbers = (
  actual: unknown,
  expected: unknown,
  matcherName: string,
  options?: MatcherHintOptions,
): void => {

View on GitHub (pinned to 8e6d128e4a)

Solutions

Coerce the expected value with Number(...), parseInt, or parseFloat before the matcher.
Verify any imported/config variable used as the expected bound is actually defined (log it).
If comparing BigInts produced from JSON, rehydrate them with BigInt(...) instead of leaving a string.

Example fix

// before
expect(cpu).toBeGreaterThan(config.threshold);
// after
expect(cpu).toBeGreaterThan(Number(config.threshold));

Defensive patterns

Strategy: validation

Validate before calling

if (typeof expected !== 'number' && typeof expected !== 'bigint') {
  throw new TypeError(`expected bound must be number|bigint, got ${typeof expected}`);
}
expect(value).toBeGreaterThan(expected);

Type guard

const isNumberOrBigInt = (x: unknown): x is number | bigint =>
  typeof x === 'number' || typeof x === 'bigint';

Prevention

Always coerce config/env values to Number before using them as matcher bounds.
Type expected bounds explicitly as number in your helper signatures.
Run TypeScript with strict checks so non-numeric bounds are flagged at compile time.

When it happens

Trigger: Calling a numeric matcher whose expected value is not a number/bigint: expect(value).toBeGreaterThan('10'), expect(n).toBeLessThan(undefined), expect(big).toBeGreaterThan(JSON.parse('\"1\"')).

Common situations: Passing an unparsed string from process.env or a config file; comparing against an import that resolved to undefined because of a wrong/ESM-CJS path; mixing JSON-parsed values (which turn bigints into strings); typo in a variable name yielding undefined.

Related errors

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