{"id":"e342c46e13e60015","repo":"jestjs/jest","slug":"received-value-must-be-a-number-or-bigint","errorCode":null,"errorMessage":"received value must be a number or bigint","messagePattern":"received value must be a number or bigint","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/jest-matcher-utils/src/index.ts","lineNumber":186,"sourceCode":"        'this matcher must not have an expected argument',\n        printWithType('Expected', expected, printExpected),\n      ),\n    );\n  }\n};\n\n/**\n * Ensures that `actual` is of type `number | bigint`\n */\nexport const ensureActualIsNumber = (\n  actual: unknown,\n  matcherName: string,\n  options?: MatcherHintOptions,\n): void => {\n  if (typeof actual !== 'number' && typeof actual !== 'bigint') {\n    // Prepend maybe not only for backward compatibility.\n    const matcherString = (options ? '' : '[.not]') + matcherName;\n    throw new Error(\n      matcherErrorMessage(\n        matcherHint(matcherString, undefined, undefined, options),\n        `${RECEIVED_COLOR('received')} value must be a number or bigint`,\n        printWithType('Received', actual, printReceived),\n      ),\n    );\n  }\n};\n\n/**\n * Ensures that `expected` is of type `number | bigint`\n */\nexport const ensureExpectedIsNumber = (\n  expected: unknown,\n  matcherName: string,\n  options?: MatcherHintOptions,\n): void => {\n  if (typeof expected !== 'number' && typeof expected !== 'bigint') {","sourceCodeStart":168,"sourceCodeEnd":204,"githubUrl":"https://github.com/jestjs/jest/blob/f49721c78e195558b40913977c9230f5b7f559d8/packages/jest-matcher-utils/src/index.ts#L168-L204","documentation":"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.","triggerScenarios":"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'.","commonSituations":"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.","solutions":["Coerce the received value to a number before the matcher: expect(Number(actual)).toBeGreaterThan(5), or for dates use expect(actual.getTime()).toBeGreaterThan(...).","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.","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.","For NaN specifically, use expect(Number.isNaN(actual)).toBe(true) instead of a numeric comparison."],"exampleFix":"// before\nexpect(process.env.PORT).toBeGreaterThan(1024);\n// after\nexpect(Number(process.env.PORT)).toBeGreaterThan(1024);","handlingStrategy":"validation","validationCode":"function assertNumericActual(actual: unknown, matcher: string) {\n  if (typeof actual !== 'number' && typeof actual !== 'bigint') {\n    throw new Error(`Cannot use ${matcher}: actual is ${typeof actual}`);\n  }\n}\nassertNumericActual(port, 'toBeGreaterThan');\nexpect(port).toBeGreaterThan(1024);","typeGuard":"const isNumeric = (v: unknown): v is number | bigint =>\n  typeof v === 'number' || typeof v === 'bigint';\n\nif (isNumeric(actual)) {\n  expect(actual).toBeGreaterThan(5);\n} else {\n  expect(Number(actual)).toBeGreaterThan(5);\n}","tryCatchPattern":null,"preventionTips":["Always convert env vars and parsed JSON numbers with Number() before numeric matchers.","For Date values, compare Date.now() or .getTime() rather than the Date object.","Add a TypeScript type annotation on the variable so the editor warns before the matcher is reached."],"tags":["matchers","type-error","numeric","jest-matcher-utils"],"analyzedSha":"f49721c78e195558b40913977c9230f5b7f559d8","analyzedAt":"2026-08-03T20:16:28.571Z","schemaVersion":2}