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` throws (packages/jest-cli/src/args.ts:51) when `--maxWorkers` is present on the command line but its value is `undefined` — i.e. the flag was given without an argument. The message also hints that `-w` is the alias for `--maxWorkers`, which is commonly confused with `--watch`.

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 f49721c78e)

Solutions

Provide a numeric value or percentage: `--maxWorkers 2` or `--maxWorkers 50%`.
If you meant watch mode, use `--watch` (long form) instead of `-w`.
If the value comes from an env var, default it: `--maxWorkers ${MAX_WORKERS:-2}`.

Example fix

# before
jest -w           # -w is the alias for --maxWorkers, needs a value
jest --maxWorkers  # no value

# after
jest --watch       # if you wanted watch mode
jest --maxWorkers 2 # if you wanted to cap workers

Defensive patterns

Strategy: validation

Validate before calling

function resolveMaxWorkers(raw?: string): string | undefined {
  if (raw === undefined || raw === '') {
    throw new Error('--maxWorkers requires a value (e.g. 2 or 50%), or did you mean --watch?');
  }
  return raw;
}

Type guard

const hasMaxWorkersValue = (a: any) =>
  Object.prototype.hasOwnProperty.call(a, 'maxWorkers') && a.maxWorkers !== undefined;

Prevention

Remember `-w` aliases --maxWorkers, NOT --watch.
Default env-derived worker counts: `${MW:-2}`.
Double-check trailing flags in generated command lines.

When it happens

Trigger: `jest --maxWorkers` (trailing flag with no value), a truncated script, or accidentally typing `jest -w` intending `--watch`.

Common situations: Confusing `-w` (maxWorkers alias) with `--watch`; env-var expansion producing an empty string; yargs stripping an empty value.

Related errors

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