jestjs/jest · error · Error

${RECEIVED_COLOR('received')} value must be a non-null objec

Error message

${RECEIVED_COLOR('received')} value must be a non-null object

What it means

Thrown by `toMatchObject` (matchers.ts:901) when the received value is not a non-null object. `toMatchObject` checks that the received object contains the expected subset of properties; it requires `typeof received === 'object' && received !== null`, so primitives, null, and undefined are rejected.

Source

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

            matcherHint(matcherName, undefined, undefined, options) +
            '\n\n' +
            `${printLabel(labelExpected)}${printExpected(expected)}\n` +
            `${printLabel(labelReceived)}${printReceived(received)}`
          );
        };

    return {message, pass};
  },

  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),
        ),
      );
    }

View on GitHub (pinned to 8e6d128e4a)

Solutions

1. Ensure received is an object: assert the source returns an object for the input.
2. If the value may be null/undefined, guard first: expect(value).toBeDefined().
3. For scalar comparisons use toEqual/toBe, not toMatchObject.
4. Default the root: expect(value ?? {}).toMatchObject({a:1}) only if an empty-object fallback is meaningful.

Example fix

// before
expect(getSettings()).toMatchObject({theme: 'dark'}); // returns undefined
expect(status).toMatchObject({code: 200});            // status is a number

// after
expect(getSettings() ?? {}).toMatchObject({theme: 'dark'});
expect(status).toEqual(200);

const v = received;
if (typeof v !== 'object' || v === null) {
  throw new Error('toMatchObject requires a non-null object received value');
}
expect(v).toMatchObject({a: 1});

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

When it happens

Trigger: Calling `expect(value).toMatchObject({a:1})` where `value` is a primitive (number, string, boolean), null, undefined, or a symbol.

Common situations: A function returns a primitive in an edge case (e.g. a number code) when an object was expected; the property accessed is a scalar not an object; an optional object is null/undefined after a schema change.

Related errors

• ${EXPECTED_COLOR('expected')} 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/db4962f3c8630cfe. Report an issue: GitHub.