{"record":{"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":"exception","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/8e6d128e4a278059ecddecaa97400b04c8ae5fd9/packages/jest-cli/src/args.ts#L37-L73","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Provide an explicit value: jest --maxWorkers=2 or jest --maxWorkers=50%.","If you wanted watch mode, use --watch (or -w only when maxWorkers is not also aliased).","If the value comes from an env var, default it (e.g. --maxWorkers=${MAX_WORKERS:-2}) or omit the flag when empty."],"exampleFix":"// before\njest --maxWorkers\n// after\njest --maxWorkers=2\n// or, if you meant watch:\njest --watch","handlingStrategy":"validation","validationCode":"function maxWorkersArg(value: string | number | undefined): string[] {\n  if (value === undefined || value === '') return []; // omit the flag\n  if (typeof value === 'number' || /^\\d+%$/.test(value)) return ['--maxWorkers', String(value)];\n  throw new Error('maxWorkers must be a number or N% string');\n}","typeGuard":"function isValidMaxWorkers(v: unknown): v is number | string {\n  return typeof v === 'number' || (typeof v === 'string' && /^\\d+(|%)$/.test(v));\n}","tryCatchPattern":null,"preventionTips":["Default env-derived values (e.g. ${MAX_WORKERS:-2}) so they never expand to empty.","Remember -w is the alias for --maxWorkers; use --watch for watch mode.","Validate the value shape before forwarding to jest."],"tags":["jest-cli","cli-args","maxworkers","missing-argument","watch"],"backgroundTag":null,"analyzedSha":"8e6d128e4a278059ecddecaa97400b04c8ae5fd9","analyzedAt":"2026-08-10T18:11:27.960Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}