{"id":"54a7d38959aecae7","repo":"jestjs/jest","slug":"received-value-must-have-a-length-property-whose-v","errorCode":null,"errorMessage":"received value must have a length property whose value must be a number","messagePattern":"received value must have a length property whose value must be a number","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"packages/expect/src/matchers.ts","lineNumber":665,"sourceCode":"            isExpand(this.expand),\n          );\n\n    // Passing the actual and expected objects so that a custom reporter\n    // could access them, for example in order to display a custom visual diff,\n    // or create a different error message\n    return {actual: received, expected, message, name: matcherName, pass};\n  },\n\n  toHaveLength(received: any, expected: number) {\n    const matcherName = 'toHaveLength';\n    const isNot = this.isNot;\n    const options: MatcherHintOptions = {\n      isNot,\n      promise: this.promise,\n    };\n\n    if (typeof received?.length !== 'number') {\n      throw new TypeError(\n        matcherErrorMessage(\n          matcherHint(matcherName, undefined, undefined, options),\n          `${RECEIVED_COLOR(\n            'received',\n          )} value must have a length property whose value must be a number`,\n          printWithType('Received', received, printReceived),\n        ),\n      );\n    }\n\n    ensureExpectedIsNonNegativeInteger(expected, matcherName, options);\n\n    const pass = received.length === expected;\n\n    const message = () => {\n      const labelExpected = 'Expected length';\n      const labelReceivedLength = 'Received length';\n      const labelReceivedValue = `Received ${getType(received)}`;","sourceCodeStart":647,"sourceCodeEnd":683,"githubUrl":"https://github.com/jestjs/jest/blob/f49721c78e195558b40913977c9230f5b7f559d8/packages/expect/src/matchers.ts#L647-L683","documentation":"Thrown by `toHaveLength` (matchers.ts:656) when the received value either has no `.length` property, or its `.length` is not a number. The matcher reads `received.length` and compares it via `===` to the expected integer, so a missing or non-numeric length breaks the comparison. The check uses optional chaining (`received?.length`) so null/undefined received values also surface here rather than crashing.","triggerScenarios":"Calling `expect(value).toHaveLength(3)` where `value` is a plain object without `length` (`{a:1}`), a number, a boolean, `null`/`undefined`, or an object whose `length` is a string (e.g. some jQuery-like wrappers).","commonSituations":"Asserting length on a Map/Set (they have `.size`, not `.length`); on a Promise; on a function reference before invocation; on `null` from a failed query; mixing up `Object.keys(obj).length` (works) with checking `obj` directly.","solutions":["If checking a Map/Set, use `.size` and assert on `map.size` directly or convert: `expect([...map]).toHaveLength(3)`.","For objects, assert on keys: `expect(Object.keys(obj)).toHaveLength(3)`.","Confirm the received value is the iterable you expect — log `received` and `typeof received?.length`.","If nullish is possible, guard or fix the producer to return `[]`."],"exampleFix":"// before\nexpect(user.permissions).toHaveLength(3); // Map, no .length\n\n// after\nexpect([...user.permissions]).toHaveLength(3);","handlingStrategy":"type-guard","validationCode":"if (received == null || typeof received.length !== 'number') {\n  throw new Error(`received must have a numeric .length, got ${received == null ? String(received) : 'no length'}`);\n}\nexpect(received).toHaveLength(n);","typeGuard":"const hasNumericLength = (v: unknown): v is {length: number} =>\n  v != null && typeof (v as any).length === 'number';","tryCatchPattern":"try {\n  expect(received).toHaveLength(n);\n} catch (e) {\n  if (e instanceof TypeError && /length property/.test(e.message)) {\n    console.error('received has no numeric length; received:', received);\n  }\n  throw e;\n}","preventionTips":["Use `.size` for Map/Set or spread first: `expect([...map]).toHaveLength(n)`.","Use `Object.keys(obj).length` for plain objects.","Confirm received is an array/string/typed array before asserting length."],"tags":["jest","expect","type-validation","assertion","length","iterable"],"analyzedSha":"f49721c78e195558b40913977c9230f5b7f559d8","analyzedAt":"2026-08-03T20:16:28.571Z","schemaVersion":2}