{"record":{"id":"969c3d0e44c59227","repo":"vitest-dev/vitest","slug":"received-value-must-be-an-object-when-the-matcher","errorCode":null,"errorMessage":"Received value must be an object when the matcher has properties","messagePattern":"Received value must be an object when the matcher has properties","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/snapshot/src/client.ts","lineNumber":151,"sourceCode":"    if (!filepath) {\n      throw new Error('Snapshot cannot be used outside of test')\n    }\n\n    const snapshotState = this.getSnapshotState(filepath)\n    const testName = [name, ...(message ? [message] : [])].join(' > ')\n\n    // Probe first so we can mark as checked even on early return\n    const expectedSnapshot = snapshotState.probeExpectedSnapshot({\n      testName,\n      testId,\n      isInline,\n      inlineSnapshot,\n    })\n\n    if (typeof properties === 'object') {\n      if (typeof received !== 'object' || !received) {\n        expectedSnapshot.markAsChecked()\n        throw new Error(\n          'Received value must be an object when the matcher has properties',\n        )\n      }\n\n      let propertiesPass: boolean\n      try {\n        propertiesPass = this.options.isEqual?.(received, properties) ?? false\n      }\n      catch (err) {\n        expectedSnapshot.markAsChecked()\n        throw err\n      }\n      if (!propertiesPass) {\n        expectedSnapshot.markAsChecked()\n        return {\n          pass: false,\n          message: () => errorMessage || 'Snapshot properties mismatched',\n          actual: received,","sourceCodeStart":133,"sourceCodeEnd":169,"githubUrl":"https://github.com/vitest-dev/vitest/blob/1fa9837ec26533512fdcad8baebf249771bd340a/packages/snapshot/src/client.ts#L133-L169","documentation":"In SnapshotClient.match, when the properties option is an object (used to filter/compare a subset of received), received must also be an object. If received is null, undefined, or a primitive, the comparison cannot proceed and the error is thrown after marking the expected snapshot as checked.","triggerScenarios":"Calling toMatchSnapshot with a properties argument (second matcher arg) on a primitive received value, e.g. expect(5).toMatchSnapshot({ a: 1 }) or expect(null).toMatchSnapshot({}); also when received is undefined.","commonSituations":"Passing an expected-shape object as properties to a snapshot of a primitive; mismatch between the matcher's properties argument and the actual value type; refactoring that changed received from object to primitive without updating the assertion.","solutions":[],"exampleFix":"// before\nexpect(getCount()).toMatchSnapshot({ value: expect.any(Number) })\n// after\nexpect({ value: getCount() }).toMatchSnapshot({ value: expect.any(Number) })","handlingStrategy":"type-guard","validationCode":"if (properties != null && (typeof received !== 'object' || received === null)) {\n  throw new Error('properties matcher requires received to be a non-null object')\n}\nclient.match({ filepath, name, received, properties })","typeGuard":"function canUseProperties(received: unknown, properties: unknown): boolean { return properties == null || (typeof received === 'object' && received !== null) }","tryCatchPattern":null,"preventionTips":["Only pass properties for object snapshots","Box primitives into objects before snapshotting with properties","Add a runtime guard in custom matcher wrappers"],"tags":["snapshot","matcher","properties","validation"],"backgroundTag":null,"analyzedSha":"1fa9837ec26533512fdcad8baebf249771bd340a","analyzedAt":"2026-08-11T16:11:39.638Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}