jestjs/jest · error · Error

${matcherHint(...)} Expected properties must be an object ${

Error message

${matcherHint(...)} Expected properties must be an object
${printedWithType}

What it means

Thrown by `toMatchSnapshot` (index.ts:189-195) when the matcher is called with two or three arguments and the second argument is neither a string (treated as a hint) nor a non-null object (treated as expected properties). The runtime can't decide what the caller meant, so it surfaces a typed matcher error via `matcherErrorMessage`.

Source

Thrown at packages/jest-snapshot/src/index.ts:189

        promise: this.promise,
      };
      let printedWithType = printWithType(
        'Expected properties',
        propertiesOrHint,
        printExpected,
      );

      if (length === 3) {
        options.secondArgument = 'hint';
        options.secondArgumentColor = BOLD_WEIGHT;

        if (propertiesOrHint == null) {
          printedWithType +=
            "\n\nTo provide a hint without properties: toMatchSnapshot('hint')";
        }
      }

      throw new Error(
        matcherErrorMessage(
          matcherHint(matcherName, undefined, PROPERTIES_ARG, options),
          `Expected ${EXPECTED_COLOR('properties')} must be an object`,
          printedWithType,
        ),
      );
    }

    // Future breaking change: Snapshot hint must be a string
    // if (arguments.length === 3 && typeof hint !== 'string') {}

    properties = propertiesOrHint;
  }

  return _toMatchSnapshot({
    context: this,
    hint,
    isInline: false,

View on GitHub (pinned to f49721c78e)

Solutions

Pass an object as the second argument when you mean properties: `toMatchSnapshot({ a: 1 })`.
Pass a string when you mean a hint: `toMatchSnapshot('hint')`.
For a 3-arg call `toMatchSnapshot(properties, 'hint')`, ensure the first is a non-null object and the second a string.

Example fix

// before
expect(result).toMatchSnapshot(statusCode); // statusCode is a number

// after
expect(result).toMatchSnapshot({ statusCode });

Defensive patterns

Strategy: type-guard

Validate before calling

function isPropertiesOrHint(v: unknown): v is object | string {
  return v == null || typeof v === 'object' || typeof v === 'string';
}
if (!isPropertiesOrHint(arg)) {
  throw new Error('Pass an object for properties or a string for a hint');
}
expect(x).toMatchSnapshot(arg);

Type guard

function isProperties(v: unknown): v is object {
  return typeof v === 'object' && v !== null;
}
function isHint(v: unknown): v is string {
  return typeof v === 'string';
}

Prevention

When you want properties, pass a plain object literal at the call site.
When you want a hint, pass a string literal.
Avoid optional-chained variables as the second arg unless you've checked them.

When it happens

Trigger: `expect(x).toMatchSnapshot(123)`, `expect(x).toMatchSnapshot(true)`, or `expect(x).toMatchSnapshot(undefined, 'hint')` (the `undefined` is the offending second arg in a 3-arg call).

Common situations: Passing a variable that was meant to be an object but is `undefined`/a primitive. Mixing up argument order between properties and hint.

Related errors

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