jestjs/jest · error · TypeError

${RECEIVED_COLOR('received')} value must be a string

Error message

${RECEIVED_COLOR('received')} value must be a string

What it means

Thrown by `toMatch` (matchers.ts:823) when the received value is not a string. `toMatch` checks substring or regex membership against a string; it explicitly requires `typeof received === 'string'` before testing, refusing to coerce.

Source

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

                  : receivedPath.join('.'),
              )}\n\n${
                hasValue
                  ? `Expected value: ${printExpected(expectedValue)}\n`
                  : ''
              }Received value: ${printReceived(receivedValue)}`);

    return {message, pass};
  },

  toMatch(received: string, expected: string | RegExp) {
    const matcherName = 'toMatch';
    const options: MatcherHintOptions = {
      isNot: this.isNot,
      promise: this.promise,
    };

    if (typeof received !== 'string') {
      throw new TypeError(
        matcherErrorMessage(
          matcherHint(matcherName, undefined, undefined, options),
          `${RECEIVED_COLOR('received')} value must be a string`,
          printWithType('Received', received, printReceived),
        ),
      );
    }

    if (
      !(typeof expected === 'string') &&
      !(expected && typeof expected.test === 'function')
    ) {
      throw new Error(
        matcherErrorMessage(
          matcherHint(matcherName, undefined, undefined, options),
          `${EXPECTED_COLOR(
            'expected',
          )} value must be a string or regular expression`,

View on GitHub (pinned to 8e6d128e4a)

Solutions

1. Ensure received is a string: stringify numbers, call .toISOString() on dates, .toString() where meaningful.
2. If testing object/array shape, use toEqual/toMatchObject instead of toMatch.
3. If the value may be undefined, guard or default it: expect(String(value ?? '')).toMatch(...).
4. Fix the source to return the string field you actually intended to match.

Example fix

// before
expect(response.code).toMatch(/^ERR/); // response.code is a number
expect(event.timestamp).toMatch(/2024/);  // Date object

// after
expect(String(response.code)).toMatch(/^ERR/);
expect(event.timestamp.toISOString()).toMatch(/2024/);

const v = received;
if (typeof v !== 'string') {
  throw new Error('toMatch requires a string received value');
}
expect(v).toMatch(/pattern/);

const isString = (v: unknown): v is string => typeof v === 'string';

When it happens

Trigger: Calling `expect(value).toMatch(/pattern/)` or `expect(value).toMatch('sub')` where `value` is a number, object, null, undefined, array, or boolean.

Common situations: Value is undefined because a function returned early; value is a number that the developer assumed would be stringified; the property accessed is actually an object; a Date object passed instead of its ISO string.

Related errors

• ${EXPECTED_COLOR('expected')} value must be a string if ${RE
• ${EXPECTED_COLOR('expected')} value must be a string or regu
• ${EXPECTED_COLOR('expected')} value must be a number
• ${RECEIVED_COLOR('received')} value must be a number
• ${EXPECTED_COLOR('expected')} value must be a function

AI-assisted analysis of jestjs/jest@8e6d128e4a (2026-08-10). Data as JSON: /api/errors/6330ece613837ae1. Report an issue: GitHub.