{"id":"6199b394181a34fb","repo":"jestjs/jest","slug":"received-value-must-be-a-non-null-object","errorCode":null,"errorMessage":"received value must be a non-null object","messagePattern":"received value must be a non-null object","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/expect/src/matchers.ts","lineNumber":902,"sourceCode":"            matcherHint(matcherName, undefined, undefined, options) +\n            '\\n\\n' +\n            `${printLabel(labelExpected)}${printExpected(expected)}\\n` +\n            `${printLabel(labelReceived)}${printReceived(received)}`\n          );\n        };\n\n    return {message, pass};\n  },\n\n  toMatchObject(received: object, expected: object) {\n    const matcherName = 'toMatchObject';\n    const options: MatcherHintOptions = {\n      isNot: this.isNot,\n      promise: this.promise,\n    };\n\n    if (typeof received !== 'object' || received === null) {\n      throw new Error(\n        matcherErrorMessage(\n          matcherHint(matcherName, undefined, undefined, options),\n          `${RECEIVED_COLOR('received')} value must be a non-null object`,\n          printWithType('Received', received, printReceived),\n        ),\n      );\n    }\n\n    if (typeof expected !== 'object' || expected === null) {\n      throw new Error(\n        matcherErrorMessage(\n          matcherHint(matcherName, undefined, undefined, options),\n          `${EXPECTED_COLOR('expected')} value must be a non-null object`,\n          printWithType('Expected', expected, printExpected),\n        ),\n      );\n    }\n","sourceCodeStart":884,"sourceCodeEnd":920,"githubUrl":"https://github.com/jestjs/jest/blob/f49721c78e195558b40913977c9230f5b7f559d8/packages/expect/src/matchers.ts#L884-L920","documentation":"Thrown by `toMatchObject` (matchers.ts:894) when the value passed to `expect(...)` is not a non-null object. `toMatchObject` performs a subset deep-equality check (`equals` with `subsetEquality` tester) that walks properties, so it requires a real object; primitives, null, and undefined cannot be subset-matched. The check uses `typeof received !== 'object' || received === null`, so arrays pass (they are objects) but `null` does not.","triggerScenarios":"Calling `expect(value).toMatchObject({...})` where `value` is a string, number, boolean, undefined, null, or a function. Common with `expect(fetchThing()).toMatchObject({id: 1})` where `fetchThing` returns undefined or the call wasn't awaited.","commonSituations":"Async function not awaited; API returning null for a 404; consuming a primitive where an object wrapper was expected; refactor that flattened an object into a string; mock forgetting to return an object.","solutions":["If async, await it: `expect(await fetchThing()).toMatchObject({id: 1})`.","Confirm the producer returns an object — log `typeof value` and the value.","Use `.resolves.toMatchObject({...})` for promise assertions.","If null is legitimately possible, guard: `expect(value ?? {}).toMatchObject({...})` only makes sense if you also expect an empty object."],"exampleFix":"// before\nexpect(api.getUser(id)).toMatchObject({id}); // forgot await\n\n// after\nexpect(await api.getUser(id)).toMatchObject({id});","handlingStrategy":"type-guard","validationCode":"if (typeof received !== 'object' || received === null) {\n  throw new Error(`received must be a non-null object, got ${received === null ? 'null' : typeof received}`);\n}\nexpect(received).toMatchObject(subset);","typeGuard":"const isNonNullObject = (v: unknown): v is Record<string, unknown> =>\n  typeof v === 'object' && v !== null;","tryCatchPattern":"try {\n  expect(received).toMatchObject(subset);\n} catch (e) {\n  if (e instanceof Error && /received value must be a non-null object/.test(e.message)) {\n    console.error('received was', typeof received, received);\n  }\n  throw e;\n}","preventionTips":["Await async producers or use `.resolves.toMatchObject(...)`.","Assert `toBeDefined()` before deep matching to localize failures.","Type producers as returning `object` so TypeScript flags misuse."],"tags":["jest","expect","type-validation","assertion","object","async"],"analyzedSha":"f49721c78e195558b40913977c9230f5b7f559d8","analyzedAt":"2026-08-03T20:16:28.571Z","schemaVersion":2}