jestjs/jest · error · ValidationError

${key} has to be of type string or number

Error message

${key} has to be of type string or number

What it means

Thrown by `_validate` (validate.ts:56-62) as a special-case check for the `maxWorkers` config option. Because `maxWorkers` legitimately accepts multiple types (a number of workers, or a percentage string like `'50%'`), it bypasses the generic validator and is checked here: anything that is neither string nor number fails with the fixed example `maxWorkers=50%` or `maxWorkers=3`.

Source

Thrown at packages/jest-validate/src/validate.ts:57

      typeof options.deprecate === 'function'
    ) {
      const isDeprecatedKey = options.deprecate(
        config,
        key,
        options.deprecatedConfig,
        options,
      );

      hasDeprecationWarnings = hasDeprecationWarnings || isDeprecatedKey;
    } else if (allowsMultipleTypes(key)) {
      const value = config[key];

      if (
        typeof options.condition === 'function' &&
        typeof options.error === 'function'
      ) {
        if (key === 'maxWorkers' && !isOfTypeStringOrNumber(value)) {
          throw new ValidationError(
            'Validation Error',
            `${key} has to be of type string or number`,
            'maxWorkers=50% or\nmaxWorkers=3',
          );
        }
      }
    } else if (Object.hasOwnProperty.call(exampleConfig, key)) {
      if (
        typeof options.condition === 'function' &&
        typeof options.error === 'function' &&
        !options.condition(config[key], exampleConfig[key])
      ) {
        options.error(key, config[key], exampleConfig[key], options, path);
      }
    } else if (
      shouldSkipValidationForPath(path, key, options.recursiveDenylist)
    ) {
      // skip validating unknown options inside blacklisted paths

View on GitHub (pinned to f49721c78e)

Solutions

1. Set `maxWorkers` to a number (`maxWorkers: 4`) or a percentage string (`maxWorkers: '50%'`).
2. If deriving from env, coerce explicitly: `const mw = process.env.MW ? Number(process.env.MW) : '50%';`.
3. Avoid objects/booleans; if you need conditional behavior, branch in JS to pick a number or string.

Example fix

// before
module.exports = { maxWorkers: { count: 4 } }; // object - rejected
// after
module.exports = { maxWorkers: 4 };

const { getType } = require('@jest/get-type');
if (['maxWorkers'].includes(key) && !['number','string'].includes(getType(value)))
  throw new Error('maxWorkers must be a number or a string like "50%"');

const isValidMaxWorkers = (v: unknown): boolean =>
  typeof v === 'number' || typeof v === 'string';

When it happens

Trigger: Setting `maxWorkers` to a non-string-non-number value: a boolean (`maxWorkers: true`), an object, an array, `null`, or `undefined` propagated by accident. Numbers and strings (including `'50%'`) are accepted.

Common situations: Passing `--maxWorkers` via an env var that arrives as something unexpected; a config preset that sets `maxWorkers` conditionally and falls through to `null`; typos like `maxWorkers: { count: 4 }`.

Related errors

• Option "${path}.${option}" must be of type: ${validTyp
• The option summaryThreshold should be a number
• Custom snapshot resolver must implement a `${propName}` as a
• ● Invalid transformer module: "${slash(transformPath)}" sp
• Invalid first argument, ${descriptor}. It must be a named cl

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