{"record":{"id":"c6bce63cfd6ce87c","repo":"jestjs/jest","slug":"expectedargument-must-be-a-positive-integer","errorCode":null,"errorMessage":"${expectedArgument} must be a positive integer","messagePattern":"(.+?) must be a positive integer","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/expect/src/spyMatchers.ts","lineNumber":969,"sourceCode":"  [number, ...Array<unknown>]\n> =>\n  function (received: any, nth, ...expected): SyncExpectationResult {\n    const expectedArgument = 'n';\n    const options: MatcherHintOptions = {\n      expectedColor: (arg: string) => arg,\n      isNot: this.isNot,\n      promise: this.promise,\n      secondArgument: '...expected',\n    };\n    ensureMockOrSpy(\n      received,\n      'toHaveBeenNthCalledWith',\n      expectedArgument,\n      options,\n    );\n\n    if (!Number.isSafeInteger(nth) || nth < 1) {\n      throw new Error(\n        matcherErrorMessage(\n          matcherHint(\n            'toHaveBeenNthCalledWith',\n            undefined,\n            expectedArgument,\n            options,\n          ),\n          `${expectedArgument} must be a positive integer`,\n          printWithType(expectedArgument, nth, stringify),\n        ),\n      );\n    }\n\n    const receivedIsSpy = isSpy(received);\n    const receivedName = receivedIsSpy ? 'spy' : received.getMockName();\n\n    const calls = receivedIsSpy\n      ? received.calls.all().map((x: any) => x.args)","sourceCodeStart":951,"sourceCodeEnd":987,"githubUrl":"https://github.com/jestjs/jest/blob/8e6d128e4a278059ecddecaa97400b04c8ae5fd9/packages/expect/src/spyMatchers.ts#L951-L987","documentation":"Thrown by `toHaveBeenNthCalledWith` (spyMatchers.ts:968) when the `nth` argument is not a safe positive integer. The matcher checks `Number.isSafeInteger(nth) && nth >= 1` because call indices are 1-based; zero, negatives, NaN, Infinity, fractions, and non-numbers are all invalid.","triggerScenarios":"Calling `expect(fn).toHaveBeenNthCalledWith(0, ...)` (zero, not 1-based), a negative, a float like 1.5, NaN, a string like '1', undefined, or a computed index that is off-by-one against the 1-based convention.","commonSituations":"Off-by-one from assuming 0-based indexing (most common); a loop variable or array length used directly as nth; nth derived from a 0-based findIndex result without +1; passing an optional that was undefined.","solutions":["Use 1-based indexing: the first call is nth=1, not nth=0.","If deriving from a 0-based index, add 1: toHaveBeenNthCalledWith(i + 1, ...).","Ensure nth is a safe integer (not NaN/Infinity/fraction) before the call.","For the last call prefer toHaveBeenLastCalledWith; for the only call just toHaveBeenCalledWith."],"exampleFix":"// before\nexpect(fn).toHaveBeenNthCalledWith(0, 'first');\nexpect(fn).toHaveBeenNthCalledWith(i, args); // i is 0-based\n\n// after\nexpect(fn).toHaveBeenNthCalledWith(1, 'first');\nexpect(fn).toHaveBeenNthCalledWith(i + 1, args);","handlingStrategy":"validation","validationCode":"const nth = index;\nif (!Number.isSafeInteger(nth) || nth < 1) {\n  throw new Error('toHaveBeenNthCalledWith nth must be a positive integer (1-based)');\n}\nexpect(fn).toHaveBeenNthCalledWith(nth, ...args);","typeGuard":"const isPositiveInteger = (v: unknown): v is number =>\n  typeof v === 'number' && Number.isSafeInteger(v) && v >= 1;","tryCatchPattern":null,"preventionTips":["Remember call indices are 1-based: first call is nth=1.","Convert 0-based indices with +1 before the matcher.","Prefer toHaveBeenLastCalledWith for the last call."],"tags":["jest","expect","matcher","spy","validation","tohavebeennthcalledwith","index"],"backgroundTag":null,"analyzedSha":"8e6d128e4a278059ecddecaa97400b04c8ae5fd9","analyzedAt":"2026-08-10T18:11:27.960Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}