jestjs/jest · error · Error

expected path must not be an empty array

Error message

expected path must not be an empty array

What it means

Thrown by `toHaveProperty` (matchers.ts:711) when the expected path is an array but its length is zero. An empty path array has no keys to traverse and would always trivially match the root object, which is never what the developer intended. Jest computes `expectedPathLength` (via `pathAsArray(...).length` for strings or `.length` for arrays) and rejects the `array` type with zero length specifically.

Source

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

    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`,
          printWithType('Expected', expectedPath, printExpected),
        ),
      );
    }

    const result = getPath(received, expectedPath);
    const {lastTraversedObject, endPropIsDefined, hasEndProp, value} = result;
    const receivedPath = result.traversedPath;
    const hasCompletePath = receivedPath.length === expectedPathLength;
    const receivedValue = hasCompletePath ? result.value : lastTraversedObject;

    const pass =
      hasValue && endPropIsDefined
        ? equals(value, expectedValue, [
            ...this.customTesters,

View on GitHub (pinned to f49721c78e)

Solutions

1. Provide at least one key in the array: `.toHaveProperty(['key'])`.
2. If the path is dynamic, fall back to a meaningful default or skip the assertion when empty.
3. Inspect how the path array is constructed — log it before the assertion.
4. If you meant to assert on the root, use a different assertion like `expect(obj).toEqual(expect.any(Object))`.

Example fix

// before
const keys = path.split('.').filter(Boolean); // [] for empty path
expect(obj).toHaveProperty(keys);

// after
const keys = path.split('.').filter(Boolean);
if (keys.length > 0) expect(obj).toHaveProperty(keys);

if (Array.isArray(path) && path.length === 0) {
  throw new Error('path array must not be empty');
}
expect(obj).toHaveProperty(path);

const isNonEmptyPath = (v: unknown): boolean =>
  typeof v === 'string' ? v.length > 0 : Array.isArray(v) && v.length > 0;

try {
  expect(obj).toHaveProperty(path);
} catch (e) {
  if (e instanceof Error && /must not be an empty array/.test(e.message)) {
    console.error('path was an empty array; supply at least one key');
  }
  throw e;
}

When it happens

Trigger: Calling `expect(obj).toHaveProperty([])` literally, or `.toHaveProperty(keys)` where `keys` is an array that was dynamically built and ended up empty (e.g. split a string with no delimiter, or a filter that removed all entries).

Common situations: Building a path array from user input or config where the input was blank; chaining operations that produced `[]` instead of `['']`; refactor that wrapped a path in an array conditionally and hit the empty case.

Related errors

• expected path must be a string or array
• ${expectedArgument} must be a positive integer
• expected value must be a number
• received value must be a number
• expected value must be a function

AI-assisted analysis of jestjs/jest@f49721c78e (2026-08-03). Data as JSON: /data/errors/43623cfe1b7c2bb1.json. Report an issue: GitHub.