{"id":"a7a3e1af5d0c2fac","repo":"tj/commander.js","slug":"option-creation-failed-due-to-unsupportedflag","errorCode":null,"errorMessage":"option creation failed due to '${unsupportedFlag}' in option flags '${flags}'\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')","messagePattern":"option creation failed due to '(.+?)' in option flags '(.+?)'\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'\\)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/option.js","lineNumber":355,"sourceCode":"  // Normal is short and/or long.\n  if (shortFlagExp.test(flagParts[0])) shortFlag = flagParts.shift();\n  if (longFlagExp.test(flagParts[0])) longFlag = flagParts.shift();\n  // Long then short. Rarely used but fine.\n  if (!shortFlag && shortFlagExp.test(flagParts[0]))\n    shortFlag = flagParts.shift();\n  // Allow two long flags, like '--ws, --workspace'\n  // This is the supported way to have a shortish option flag.\n  if (!shortFlag && longFlagExp.test(flagParts[0])) {\n    shortFlag = longFlag;\n    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}'.`,","sourceCodeStart":337,"sourceCodeEnd":373,"githubUrl":"https://github.com/tj/commander.js/blob/ba6d13ddb4243e5913367734f8c159089ffe7834/lib/option.js#L337-L373","documentation":"Thrown by the private splitOptionFlags() helper at Option construction when a leftover flag token matches /^-[^-][^-]/: a single dash followed by two or more non-dash characters (e.g. '-ab'). A short flag must be exactly one dash plus one character; multi-character names must use a double dash. The error message explicitly suggests either a single-char short flag or a '--long, --long-alias' pair.","triggerScenarios":"Constructing new Option('-ws <value>'), new Option('-ab'), or any flags string containing a token like '-xx'. Also when intending the supported 'shortish' pattern ('--ws, --workspace') but mistakenly writing '-ws, --workspace'.","commonSituations":"Wanting a two-letter shortcut and not realizing short flags are strictly one char; copying flag spellings from another tool; auto-generating flags from config keys by prepending a single dash.","solutions":["Use a double dash for multi-character names: new Option('--ws <value>').","Or use a single-character short flag: new Option('-w <value>').","For an alias pair use two long flags: new Option('--ws, --workspace <value>').","If flags are generated dynamically, validate them with the helper in validationCode before constructing the Option."],"exampleFix":"// before\nnew Option('-ws <value>');\n\n// after\nnew Option('--ws <value>');","handlingStrategy":"validation","validationCode":"// Mirrors Commander's splitOptionFlags rules; returns an error string or null.\nfunction previewOptionFlagsError(flags) {\n  const shortFlagExp = /^-[^-]$/;\n  const longFlagExp = /^--[^-]/;\n  const flagParts = String(flags).split(/[ |,]+/).concat('guard');\n  let shortFlag, longFlag;\n  if (shortFlagExp.test(flagParts[0])) shortFlag = flagParts.shift();\n  if (longFlagExp.test(flagParts[0])) longFlag = flagParts.shift();\n  if (!shortFlag && shortFlagExp.test(flagParts[0])) shortFlag = flagParts.shift();\n  if (!shortFlag && longFlagExp.test(flagParts[0])) { shortFlag = longFlag; longFlag = flagParts.shift(); }\n  if (flagParts[0].startsWith('-')) {\n    const u = flagParts[0];\n    if (/^-[^-][^-]/.test(u)) return `short flag must be one dash + one char: '${u}' (use --long instead)`;\n    if (shortFlagExp.test(u)) return `too many short flags: '${u}'`;\n    if (longFlagExp.test(u)) return `too many long flags: '${u}'`;\n    return `unrecognised flag format: '${u}'`;\n  }\n  if (shortFlag === undefined && longFlag === undefined) return `no flags found in '${flags}'`;\n  return null;\n}\n// usage: const e = previewOptionFlagsError('-ws'); if (e) throw new Error(e);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Short flags are strictly one dash + one character; never two chars after a single dash.","For a 'shortish' two-letter option use the two-long-flags form: '--ws, --workspace'.","When flags are generated from config keys, run previewOptionFlagsError before constructing Option.","Add a unit test that constructs every option your CLI declares."],"tags":["option","flags","validation","commander"],"analyzedSha":"ba6d13ddb4243e5913367734f8c159089ffe7834","analyzedAt":"2026-08-03T20:26:04.326Z","schemaVersion":2}