{"id":"ef83bff8258e7dda","repo":"jestjs/jest","slug":"expected-path-must-be-a-string-or-array","errorCode":null,"errorMessage":"expected path must be a string or array","messagePattern":"expected path must be a string or array","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/expect/src/matchers.ts","lineNumber":738,"sourceCode":"      isNot: this.isNot,\n      promise: this.promise,\n      secondArgument: hasValue ? 'value' : '',\n    };\n\n    if (received === null || received === undefined) {\n      throw new Error(\n        matcherErrorMessage(\n          matcherHint(matcherName, undefined, expectedArgument, options),\n          `${RECEIVED_COLOR('received')} value must not be null nor undefined`,\n          printWithType('Received', received, printReceived),\n        ),\n      );\n    }\n\n    const expectedPathType = getType(expectedPath);\n\n    if (expectedPathType !== 'string' && expectedPathType !== 'array') {\n      throw new Error(\n        matcherErrorMessage(\n          matcherHint(matcherName, undefined, expectedArgument, options),\n          `${EXPECTED_COLOR('expected')} path must be a string or array`,\n          printWithType('Expected', expectedPath, printExpected),\n        ),\n      );\n    }\n\n    const expectedPathLength =\n      typeof expectedPath === 'string'\n        ? pathAsArray(expectedPath).length\n        : expectedPath.length;\n\n    if (expectedPathType === 'array' && expectedPathLength === 0) {\n      throw new Error(\n        matcherErrorMessage(\n          matcherHint(matcherName, undefined, expectedArgument, options),\n          `${EXPECTED_COLOR('expected')} path must not be an empty array`,","sourceCodeStart":720,"sourceCodeEnd":756,"githubUrl":"https://github.com/jestjs/jest/blob/f49721c78e195558b40913977c9230f5b7f559d8/packages/expect/src/matchers.ts#L720-L756","documentation":"Thrown by `toHaveProperty` (matchers.ts:711) when the first argument (the key path) is neither a string nor an array. `toHaveProperty` accepts a dot/bracket string (`'a.b[0].c'`) or an array of keys (`['a', 'b', '0', 'c']`); any other type (number, object, null) cannot be traversed. The check uses `getType(expectedPath)` and rejects anything whose type isn't `'string'` or `'array'`.","triggerScenarios":"Calling `expect(obj).toHaveProperty(42)` (number), `.toHaveProperty({key: 'a'})` (object), `.toHaveProperty(null)`, `.toHaveProperty(true)`, or passing a Symbol. Note: a single-key string is valid, but a raw number like an array index is not — it must be `'42'` or `['42']`.","commonSituations":"Passing a computed numeric key directly instead of wrapping as string; passing a path object from a helper library; refactor that changed a path variable from string to number; copy-paste from a different matcher API.","solutions":["Convert the path to a string: `.toHaveProperty(String(key))`.","Use the array form for clarity: `.toHaveProperty([String(key)])`.","Log `typeof expectedPath` and `Array.isArray(expectedPath)` to confirm shape.","If the path comes from a dynamic source, validate it before the test."],"exampleFix":"// before\nexpect(arr).toHaveProperty(index); // index is a number\n\n// after\nexpect(arr).toHaveProperty(String(index));","handlingStrategy":"type-guard","validationCode":"if (typeof path !== 'string' && !Array.isArray(path)) {\n  throw new Error(`path must be string or array, got ${typeof path}`);\n}\nexpect(obj).toHaveProperty(path);","typeGuard":"const isPath = (v: unknown): v is string | Array<unknown> =>\n  typeof v === 'string' || Array.isArray(v);","tryCatchPattern":"try {\n  expect(obj).toHaveProperty(path);\n} catch (e) {\n  if (e instanceof Error && /path must be a string or array/.test(e.message)) {\n    console.error('path was', typeof path, path);\n  }\n  throw e;\n}","preventionTips":["Wrap numeric keys as strings: `String(index)`.","Use the array form `[a, b]` for clarity with computed keys.","Validate dynamic paths before constructing the assertion."],"tags":["jest","expect","type-validation","assertion","object-path","string"],"analyzedSha":"f49721c78e195558b40913977c9230f5b7f559d8","analyzedAt":"2026-08-03T20:16:28.571Z","schemaVersion":2}