jestjs/jest · error · Error

${EXPECTED_COLOR('expected')} value must be a non-null objec

Error message

${EXPECTED_COLOR('expected')} value must be a non-null object

What it means

Thrown by `toMatchObject` (matchers.ts:911) when the expected value is not a non-null object. The expected argument defines the subset of properties to verify, so it must be a plain object (or array, which is an object). Primitives, null, and undefined are rejected before the subset equality check.

Source

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

  toMatchObject(received: object, expected: object) {
    const matcherName = 'toMatchObject';
    const options: MatcherHintOptions = {
      isNot: this.isNot,
      promise: this.promise,
    };

    if (typeof received !== 'object' || received === null) {
      throw new Error(
        matcherErrorMessage(
          matcherHint(matcherName, undefined, undefined, options),
          `${RECEIVED_COLOR('received')} value must be a non-null object`,
          printWithType('Received', received, printReceived),
        ),
      );
    }

    if (typeof expected !== 'object' || expected === null) {
      throw new Error(
        matcherErrorMessage(
          matcherHint(matcherName, undefined, undefined, options),
          `${EXPECTED_COLOR('expected')} value must be a non-null object`,
          printWithType('Expected', expected, printExpected),
        ),
      );
    }

    const pass = equals(received, expected, [
      ...this.customTesters,
      iterableEquality,
      subsetEquality,
    ]);

    const message = pass
      ? () =>
          // eslint-disable-next-line prefer-template
          matcherHint(matcherName, undefined, undefined, options) +

View on GitHub (pinned to 8e6d128e4a)

Solutions

1. Pass a non-null object describing the expected subset: toMatchObject({a: 1}).
2. If testing a single property value, use toHaveProperty('key', value) or toEqual instead.
3. Ensure the expected variable is a defined object, not undefined from a failed lookup.
4. For null checks use toBeNull; for existence use toHaveProperty.

Example fix

// before
expect(obj).toMatchObject();
expect(obj).toMatchObject('id');

// after
expect(obj).toMatchObject({id: 1});
// single-value case
expect(obj).toHaveProperty('id', 1);

const expected = subset;
if (typeof expected !== 'object' || expected === null) {
  throw new Error('toMatchObject expected must be a non-null object');
}
expect(obj).toMatchObject(expected);

const isNonNullObject = (v: unknown): v is object =>
  v !== null && typeof v === 'object';

When it happens

Trigger: Calling `expect(obj).toMatchObject('a')` (string), `toMatchObject(5)` (number), `toMatchObject(null)`, or `toMatchObject(undefined)` — e.g. forgetting the expected argument or passing a primitive.

Common situations: Omitting the expected object entirely; passing a string key instead of an object descriptor; passing a value from a variable that resolved to undefined; copy-paste from a toHaveProperty call.

Related errors

• ${RECEIVED_COLOR('received')} value must be a non-null objec
• ${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/e98bbdd98250f4a0. Report an issue: GitHub.