{"id":"b2c5a348bf9e7935","repo":"tj/commander.js","slug":"option-creation-failed-due-to-unsupportedflag-b2c5a3","errorCode":null,"errorMessage":"option creation failed due to '${unsupportedFlag}' in option flags '${flags}'\n- unrecognised flag format","messagePattern":"option creation failed due to '(.+?)' in option flags '(.+?)'\n- unrecognised flag format","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/option.js","lineNumber":368,"sourceCode":"  // 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":350,"sourceCodeEnd":378,"githubUrl":"https://github.com/tj/commander.js/blob/ba6d13ddb4243e5913367734f8c159089ffe7834/lib/option.js#L350-L378","documentation":"Thrown by splitOptionFlags() when a leftover token starts with '-' but matches none of the recognized shapes: not /^-[^-][^-]/ (handled by error 23), not /^-[^-]$/ (a valid short, error 24), and not /^--[^-]/ (a valid long, error 25). Examples are a lone '-', a bare '--', or '---foo'. It is the catch-all 'unrecognised flag format' branch, raised at Option construction.","triggerScenarios":"Constructing new Option('-'), new Option('--'), new Option('---foo'), or new Option('-- <value>') where the token is only dashes. Also any malformed dash-prefixed token produced by string concatenation bugs.","commonSituations":"Building flags dynamically and leaving an empty name after the dash (e.g. '-' + ''); stray '--' separator tokens accidentally included in the flags string; copy-paste artifacts; off-by-one in template literals producing '---'.","solutions":["Provide a well-formed flag: a single-char short ('-x') or a double-dash long ('--name').","If flags are assembled from variables, guard against empty/whitespace-only names before adding dashes.","Strip any stray '--' or lone '-' tokens from generated flag strings before constructing the Option."],"exampleFix":"// before\nnew Option('-');\n\n// after\nnew Option('-x');","handlingStrategy":"validation","validationCode":"// Detect dash-prefixed tokens that are not valid short or long flags.\nfunction findUnrecognisedFlag(flags) {\n  const shortFlagExp = /^-[^-]$/;\n  const longFlagExp = /^--[^-]/;\n  for (const tok of String(flags).split(/[ |,]+/)) {\n    if (!tok.startsWith('-')) continue;\n    if (/^-[^-][^-]/.test(tok) || shortFlagExp.test(tok) || longFlagExp.test(tok)) continue;\n    return tok; // e.g. '-', '--', '---foo'\n  }\n  return null;\n}\n// usage: const bad = findUnrecognisedFlag(flags); if (bad) throw new Error(`bad flag '${bad}'`);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Every dash-prefixed token must be either '-x' or '--name'; lone dashes or bare '--' are invalid.","When building flags by concatenation, never emit '-' + '' (empty name).","Strip stray '--' separators from generated flag lists before constructing Option."],"tags":["option","flags","validation","commander"],"analyzedSha":"ba6d13ddb4243e5913367734f8c159089ffe7834","analyzedAt":"2026-08-03T20:26:04.326Z","schemaVersion":2}