{"record":{"id":"eb9af1e3733ab3c5","repo":"jestjs/jest","slug":"received-color-received-value-must-have-a-le","errorCode":null,"errorMessage":"${RECEIVED_COLOR('received')} value must have a length property whose value must be a number","messagePattern":"(.+?) value must have a length property whose value must be a number","errorType":"exception","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/8e6d128e4a278059ecddecaa97400b04c8ae5fd9/packages/expect/src/matchers.ts#L647-L683","documentation":"Thrown by `toHaveLength` (matchers.ts:664) when `received.length` is not a number — including when `received` is null/undefined (no length at all) or when `.length` is a string/undefined. The matcher reads `received?.length` and requires it to be a finite numeric length before comparing to the expected count.","triggerScenarios":"Calling `expect(value).toHaveLength(3)` where `value` is a number (no length), a plain object without a length property, null, undefined, a boolean, or an object whose length is non-numeric.","commonSituations":"Asserting length on a single object instead of an array; a function returned a count number rather than the collection; the value is a Map/Set (use .size, not .length); an optional collection is undefined.","solutions":["Assert on an array or string (which have numeric .length), not a number or plain object.","For Map/Set use the size property: expect(map.size).toBe(3) rather than toHaveLength.","If the value may be undefined, default it: expect(value ?? []).toHaveLength(3).","Confirm the function returns the collection itself, not its length or an element."],"exampleFix":"// before\nexpect(getCount()).toHaveLength(3); // getCount returns a number\nexpect(mySet).toHaveLength(3);        // Set has .size\n\n// after\nexpect(getCount()).toBe(3);\nexpect(mySet.size).toBe(3);\nexpect(getItems()).toHaveLength(3);   // array","handlingStrategy":"type-guard","validationCode":"const v = received;\nif (v == null || typeof v.length !== 'number') {\n  throw new Error('toHaveLength requires a value with numeric .length');\n}\nexpect(v).toHaveLength(3);","typeGuard":"const hasNumericLength = (v: unknown): v is { length: number } =>\n  v != null && typeof (v as any).length === 'number';","tryCatchPattern":null,"preventionTips":["Use .size for Map/Set, not toHaveLength.","Assert on the collection itself, not a count number.","Confirm the function returns the array, not its length."],"tags":["jest","expect","matcher","type-error","tohavelength","array"],"backgroundTag":null,"analyzedSha":"8e6d128e4a278059ecddecaa97400b04c8ae5fd9","analyzedAt":"2026-08-10T18:11:27.960Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}