jestjs/jest · error · TypeError

${RECEIVED_COLOR('received')} value must have a length prope

Error message

${RECEIVED_COLOR('received')} value must have a length property whose value must be a number

What it means

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.

Source

Thrown at packages/expect/src/matchers.ts:665

            isExpand(this.expand),
          );

    // Passing the actual and expected objects so that a custom reporter
    // could access them, for example in order to display a custom visual diff,
    // or create a different error message
    return {actual: received, expected, message, name: matcherName, pass};
  },

  toHaveLength(received: any, expected: number) {
    const matcherName = 'toHaveLength';
    const isNot = this.isNot;
    const options: MatcherHintOptions = {
      isNot,
      promise: this.promise,
    };

    if (typeof received?.length !== 'number') {
      throw new TypeError(
        matcherErrorMessage(
          matcherHint(matcherName, undefined, undefined, options),
          `${RECEIVED_COLOR(
            'received',
          )} value must have a length property whose value must be a number`,
          printWithType('Received', received, printReceived),
        ),
      );
    }

    ensureExpectedIsNonNegativeInteger(expected, matcherName, options);

    const pass = received.length === expected;

    const message = () => {
      const labelExpected = 'Expected length';
      const labelReceivedLength = 'Received length';
      const labelReceivedValue = `Received ${getType(received)}`;

View on GitHub (pinned to 8e6d128e4a)

Solutions

1. Assert on an array or string (which have numeric .length), not a number or plain object.
2. For Map/Set use the size property: expect(map.size).toBe(3) rather than toHaveLength.
3. If the value may be undefined, default it: expect(value ?? []).toHaveLength(3).
4. Confirm the function returns the collection itself, not its length or an element.

Example fix

// before
expect(getCount()).toHaveLength(3); // getCount returns a number
expect(mySet).toHaveLength(3);        // Set has .size

// after
expect(getCount()).toBe(3);
expect(mySet.size).toBe(3);
expect(getItems()).toHaveLength(3);   // array

const v = received;
if (v == null || typeof v.length !== 'number') {
  throw new Error('toHaveLength requires a value with numeric .length');
}
expect(v).toHaveLength(3);

const hasNumericLength = (v: unknown): v is { length: number } =>
  v != null && typeof (v as any).length === 'number';

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• ${EXPECTED_COLOR('expected')} value must be a number
• ${RECEIVED_COLOR('received')} value must be a number
• ${EXPECTED_COLOR('expected')} value must be a function
• ${RECEIVED_COLOR('received')} value must not be null nor und
• ${EXPECTED_COLOR('expected')} value must be a string if ${RE

AI-assisted analysis of jestjs/jest@8e6d128e4a (2026-08-10). Data as JSON: /api/errors/eb9af1e3733ab3c5. Report an issue: GitHub.