jestjs/jest · error · Error

${EXPECTED_COLOR('expected')} path must be a string or array

Error message

${EXPECTED_COLOR('expected')} path must be a string or array

What it means

Thrown by `toHaveProperty` (matchers.ts:737) when the path argument is neither a string nor an array. The path can be a dotted string ('a.b.c') or an array of keys (['a','b','c']); any other type (number, object, null, undefined) is rejected before traversal via `getType`.

Source

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

      isNot: this.isNot,
      promise: this.promise,
      secondArgument: hasValue ? 'value' : '',
    };

    if (received === null || received === undefined) {
      throw new Error(
        matcherErrorMessage(
          matcherHint(matcherName, undefined, expectedArgument, options),
          `${RECEIVED_COLOR('received')} value must not be null nor undefined`,
          printWithType('Received', received, printReceived),
        ),
      );
    }

    const expectedPathType = getType(expectedPath);

    if (expectedPathType !== 'string' && expectedPathType !== 'array') {
      throw new Error(
        matcherErrorMessage(
          matcherHint(matcherName, undefined, expectedArgument, options),
          `${EXPECTED_COLOR('expected')} path must be a string or array`,
          printWithType('Expected', expectedPath, printExpected),
        ),
      );
    }

    const expectedPathLength =
      typeof expectedPath === 'string'
        ? pathAsArray(expectedPath).length
        : expectedPath.length;

    if (expectedPathType === 'array' && expectedPathLength === 0) {
      throw new Error(
        matcherErrorMessage(
          matcherHint(matcherName, undefined, expectedArgument, options),
          `${EXPECTED_COLOR('expected')} path must not be an empty array`,

View on GitHub (pinned to 8e6d128e4a)

Solutions

1. Pass the path as a dotted string: toHaveProperty('a.b') or as an array of strings: toHaveProperty(['a','b']).
2. Coerce numeric keys to strings when building a path: String(index).
3. If you omitted the path, add it: toHaveProperty('key') is required (unlike toBe).
4. Build array paths from string parts only: ['users', String(id), 'name'].

Example fix

// before
expect(obj).toHaveProperty(2);
expect(obj).toHaveProperty();

// after
expect(obj).toHaveProperty('items.2');
expect(obj).toHaveProperty(['items', '2']);
expect(obj).toHaveProperty('id');

const path = expectedPath;
if (typeof path !== 'string' && !Array.isArray(path)) {
  throw new Error('toHaveProperty path must be a string or array of keys');
}
expect(obj).toHaveProperty(path);

const isPath = (v: unknown): v is string | Array<string> =>
  typeof v === 'string' || (Array.isArray(v) && v.every(p => typeof p === 'string'));

When it happens

Trigger: Calling `expect(obj).toHaveProperty(2)` (number), `toHaveProperty(null)`, `toHaveProperty({key: 'x'})` (object), or omitting the path argument so it is undefined.

Common situations: Passing a numeric key as the path instead of a string key ('2'); passing an object descriptor by mistake; forgetting the path argument entirely; dynamic path built from non-string parts.

Related errors

• ${EXPECTED_COLOR('expected')} path must not be an empty arra
• ${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

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