jestjs/jest · error · Error

The --maxWorkers (-w) option requires a number or string to…

Error message

The --maxWorkers (-w) option requires a number or string to be specified.
Example usage: jest --maxWorkers 2
Example usage: jest --maxWorkers 50%
Or did you mean --watch?

What it means

check() rejects an explicitly-present but undefined --maxWorkers (args.ts:51-61), i.e. when the flag was given with no value. maxWorkers must be a number or a percentage string; the message also hints that the user may have meant --watch (whose short alias is -w, easily confused with -w for maxWorkers).

Solutions

  1. Provide an explicit value: jest --maxWorkers=2 or jest --maxWorkers=50%.
  2. If you wanted watch mode, use --watch (or -w only when maxWorkers is not also aliased).
  3. If the value comes from an env var, default it (e.g. --maxWorkers=${MAX_WORKERS:-2}) or omit the flag when empty.

Example fix

// before
jest --maxWorkers
// after
jest --maxWorkers=2
// or, if you meant watch:
jest --watch
Defensive patterns

Strategy: validation

Validate before calling

function maxWorkersArg(value: string | number | undefined): string[] {
  if (value === undefined || value === '') return []; // omit the flag
  if (typeof value === 'number' || /^\d+%$/.test(value)) return ['--maxWorkers', String(value)];
  throw new Error('maxWorkers must be a number or N% string');
}

Type guard

function isValidMaxWorkers(v: unknown): v is number | string {
  return typeof v === 'number' || (typeof v === 'string' && /^\d+(|%)$/.test(v));
}

Prevention

When it happens

Trigger: Running jest --maxWorkers (no value); jest -w (no value) where the user intended --watch; a script that conditionally appends --maxWorkers but the value variable is empty.

Common situations: Typing -w expecting watch; CI env var (e.g. $MAX_WORKERS) that expanded to empty; shell-quoting that swallowed the value; copying a flag from docs without its argument.

Related errors

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

Appendix: source

Thrown at packages/jest-cli/src/args.ts:55

  if (argv.onlyFailures && argv.watchAll) {
    throw new Error(
      'Both --onlyFailures and --watchAll were specified, only one is allowed.',
    );
  }

  if (argv.findRelatedTests && argv._.length === 0) {
    throw new Error(
      'The --findRelatedTests option requires file paths to be specified.\n' +
        'Example usage: jest --findRelatedTests ./src/source.js ' +
        './src/index.js.',
    );
  }

  if (
    Object.prototype.hasOwnProperty.call(argv, 'maxWorkers') &&
    argv.maxWorkers === undefined
  ) {
    throw new Error(
      'The --maxWorkers (-w) option requires a number or string to be specified.\n' +
        'Example usage: jest --maxWorkers 2\n' +
        'Example usage: jest --maxWorkers 50%\n' +
        'Or did you mean --watch?',
    );
  }

  if (argv.selectProjects && argv.selectProjects.length === 0) {
    throw new Error(
      'The --selectProjects option requires the name of at least one project to be specified.\n' +
        'Example usage: jest --selectProjects my-first-project my-second-project',
    );
  }

  if (argv.ignoreProjects && argv.ignoreProjects.length === 0) {
    throw new Error(
      'The --ignoreProjects option requires the name of at least one project to be specified.\n' +
        'Example usage: jest --ignoreProjects my-first-project my-second-project',

View on GitHub (pinned to 8e6d128e4a)