{"id":"4065163f4fa37588","repo":"tj/commander.js","slug":"option-creation-failed-due-to-unsupportedflag-406516","errorCode":null,"errorMessage":"option creation failed due to '${unsupportedFlag}' in option flags '${flags}'\n- too many long flags","messagePattern":"option creation failed due to '(.+?)' in option flags '(.+?)'\n- too many long flags","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/option.js","lineNumber":365,"sourceCode":"    longFlag = flagParts.shift();\n  }\n\n  // Check for unprocessed flag. Fail noisily rather than silently ignore.\n  if (flagParts[0].startsWith('-')) {\n    const unsupportedFlag = flagParts[0];\n    const baseError = `option creation failed due to '${unsupportedFlag}' in option flags '${flags}'`;\n    if (/^-[^-][^-]/.test(unsupportedFlag))\n      throw new Error(\n        `${baseError}\n- a short flag is a single dash and a single character\n  - either use a single dash and a single character (for a short flag)\n  - or use a double dash for a long option (and can have two, like '--ws, --workspace')`,\n      );\n    if (shortFlagExp.test(unsupportedFlag))\n      throw new Error(`${baseError}\n- too many short flags`);\n    if (longFlagExp.test(unsupportedFlag))\n      throw new Error(`${baseError}\n- too many long flags`);\n\n    throw new Error(`${baseError}\n- unrecognised flag format`);\n  }\n  if (shortFlag === undefined && longFlag === undefined)\n    throw new Error(\n      `option creation failed due to no flags found in '${flags}'.`,\n    );\n\n  return { shortFlag, longFlag };\n}\n","sourceCodeStart":347,"sourceCodeEnd":378,"githubUrl":"https://github.com/tj/commander.js/blob/ba6d13ddb4243e5913367734f8c159089ffe7834/lib/option.js#L347-L378","documentation":"Thrown by splitOptionFlags() when a third long flag is encountered. Commander allows up to two long flags per option (the supported '--ws, --workspace' alias pattern, where the first becomes this.short and the second this.long), but a third long token matches longFlagExp /^--[^-]/ and is rejected as 'too many long flags'. Raised at Option construction.","triggerScenarios":"Constructing new Option('--a, --b, --c'), new Option('--ws, --workspace, --work'), or any flags string listing three or more double-dash tokens.","commonSituations":"Wanting three or more aliases for one option; auto-generating synonyms from config; misunderstanding the two-long-flags alias feature and assuming it is unlimited.","solutions":["Reduce to at most two long flags: new Option('--a, --b').","Move extra aliases into a separate Option or document them in the description.","If many names must map to one action, handle them as separate options that set the same value in the action handler."],"exampleFix":"// before\nnew Option('--a, --b, --c');\n\n// after\nnew Option('--a, --b');","handlingStrategy":"validation","validationCode":"// Focused check: count long flags; >2 is rejected by Commander.\nfunction countLongFlags(flags) {\n  return (String(flags).match(/(^|[, ])--[^- ,]/g) || []).length;\n}\nfunction assertLongFlagsOk(flags) {\n  if (countLongFlags(flags) > 2) {\n    throw new Error(`too many long flags in '${flags}' (max 2, e.g. '--ws, --workspace')`);\n  }\n}\n// usage: assertLongFlagsOk('--a, --b, --c');","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Commander allows at most two long flags per option (an alias pair); a third throws.","If you need many names, map them to one value in your action handler instead of one Option.","Validate generated flag strings with countLongFlags before constructing Option."],"tags":["option","flags","validation","commander"],"analyzedSha":"ba6d13ddb4243e5913367734f8c159089ffe7834","analyzedAt":"2026-08-03T20:26:04.326Z","schemaVersion":2}