{"id":"048e7cf28efad4d0","repo":"jestjs/jest","slug":"the-maxworkers-w-option-requires-a-number-or","errorCode":null,"errorMessage":"The --maxWorkers (-w) option requires a number or string to be specified.\nExample usage: jest --maxWorkers 2\nExample usage: jest --maxWorkers 50%\nOr did you mean --watch?","messagePattern":"The --maxWorkers \\(-w\\) option requires a number or string to be specified\\.\nExample usage: jest --maxWorkers 2\nExample usage: jest --maxWorkers 50%\nOr did you mean --watch\\?","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/jest-cli/src/args.ts","lineNumber":55,"sourceCode":"  if (argv.onlyFailures && argv.watchAll) {\n    throw new Error(\n      'Both --onlyFailures and --watchAll were specified, only one is allowed.',\n    );\n  }\n\n  if (argv.findRelatedTests && argv._.length === 0) {\n    throw new Error(\n      'The --findRelatedTests option requires file paths to be specified.\\n' +\n        'Example usage: jest --findRelatedTests ./src/source.js ' +\n        './src/index.js.',\n    );\n  }\n\n  if (\n    Object.prototype.hasOwnProperty.call(argv, 'maxWorkers') &&\n    argv.maxWorkers === undefined\n  ) {\n    throw new Error(\n      'The --maxWorkers (-w) option requires a number or string to be specified.\\n' +\n        'Example usage: jest --maxWorkers 2\\n' +\n        'Example usage: jest --maxWorkers 50%\\n' +\n        'Or did you mean --watch?',\n    );\n  }\n\n  if (argv.selectProjects && argv.selectProjects.length === 0) {\n    throw new Error(\n      'The --selectProjects option requires the name of at least one project to be specified.\\n' +\n        'Example usage: jest --selectProjects my-first-project my-second-project',\n    );\n  }\n\n  if (argv.ignoreProjects && argv.ignoreProjects.length === 0) {\n    throw new Error(\n      'The --ignoreProjects option requires the name of at least one project to be specified.\\n' +\n        'Example usage: jest --ignoreProjects my-first-project my-second-project',","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/jestjs/jest/blob/f49721c78e195558b40913977c9230f5b7f559d8/packages/jest-cli/src/args.ts#L37-L73","documentation":"`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`.","triggerScenarios":"`jest --maxWorkers` (trailing flag with no value), a truncated script, or accidentally typing `jest -w` intending `--watch`.","commonSituations":"Confusing `-w` (maxWorkers alias) with `--watch`; env-var expansion producing an empty string; yargs stripping an empty value.","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}`."],"exampleFix":"# before\njest -w           # -w is the alias for --maxWorkers, needs a value\njest --maxWorkers  # no value\n\n# after\njest --watch       # if you wanted watch mode\njest --maxWorkers 2 # if you wanted to cap workers","handlingStrategy":"validation","validationCode":"function resolveMaxWorkers(raw?: string): string | undefined {\n  if (raw === undefined || raw === '') {\n    throw new Error('--maxWorkers requires a value (e.g. 2 or 50%), or did you mean --watch?');\n  }\n  return raw;\n}","typeGuard":"const hasMaxWorkersValue = (a: any) =>\n  Object.prototype.hasOwnProperty.call(a, 'maxWorkers') && a.maxWorkers !== undefined;","tryCatchPattern":null,"preventionTips":["Remember `-w` aliases --maxWorkers, NOT --watch.","Default env-derived worker counts: `${MW:-2}`.","Double-check trailing flags in generated command lines."],"tags":["jest-cli","cli-args","maxworkers","watch"],"analyzedSha":"f49721c78e195558b40913977c9230f5b7f559d8","analyzedAt":"2026-08-03T20:16:28.571Z","schemaVersion":2}