{"id":"b83dc232ba955c1f","repo":"tj/commander.js","slug":"cannot-add-option-option-flags-this-name","errorCode":null,"errorMessage":"Cannot add option '${option.flags}'${this._name && ` to command '${this._name}'`} due to conflicting flag '${matchingFlag}'\n-  already used by option '${matchingOption.flags}'","messagePattern":"Cannot add option '(.+?)'(.+?)'`\\} due to conflicting flag '(.+?)'\n-  already used by option '(.+?)'","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/command.js","lineNumber":629,"sourceCode":"\n  /**\n   * Check for option flag conflicts.\n   * Register option if no conflicts found, or throw on conflict.\n   *\n   * @param {Option} option\n   * @private\n   */\n\n  _registerOption(option) {\n    const matchingOption =\n      (option.short && this._findOption(option.short)) ||\n      (option.long && this._findOption(option.long));\n    if (matchingOption) {\n      const matchingFlag =\n        option.long && this._findOption(option.long)\n          ? option.long\n          : option.short;\n      throw new Error(`Cannot add option '${option.flags}'${this._name && ` to command '${this._name}'`} due to conflicting flag '${matchingFlag}'\n-  already used by option '${matchingOption.flags}'`);\n    }\n\n    this._initOptionGroup(option);\n    this.options.push(option);\n  }\n\n  /**\n   * Check for command name and alias conflicts with existing commands.\n   * Register command if no conflicts found, or throw on conflict.\n   *\n   * @param {Command} command\n   * @private\n   */\n\n  _registerCommand(command) {\n    const knownBy = (cmd) => {\n      return [cmd.name()].concat(cmd.aliases());","sourceCodeStart":611,"sourceCodeEnd":647,"githubUrl":"https://github.com/tj/commander.js/blob/ba6d13ddb4243e5913367734f8c159089ffe7834/lib/command.js#L611-L647","documentation":"Thrown by Command._registerOption() at lib/command.js:620-631 when a new option's short or long flag already matches an option registered on the same command. Commander keys options by flag for dispatch (the `on('option:'+oname)` listener) and for --help grouping, so duplicates would silently shadow each other.","triggerScenarios":"Two `.option('-v, --verbose')` calls on the same program; or `-v, --verbose` followed by `-v, --version` (shared `-v`); or adding an option whose `--long` collides with an existing one. The error identifies both the new flags and the conflicting existing option.","commonSituations":"Composing options from multiple modules/helpers that each define `-v`/`--verbose`; renaming an option but forgetting to remove the old declaration; merging two CLIs; auto-generated options that don't check for collisions.","solutions":["Rename one of the conflicting flags (short or long) so they are unique on the command.","If both options are the same concept, delete the duplicate declaration.","Centralize option definitions in one module and assert uniqueness before registering, especially when assembling commands programmatically."],"exampleFix":"// before (throws: -v used twice)\n.option('-v, --verbose', 'verbosity')\n.option('-v, --version', 'show version')\n\n// after\n.option('-v, --verbose', 'verbosity')\n.option('-V, --version', 'show version')","handlingStrategy":"validation","validationCode":"function registerOptions(cmd, options) {\n  const seen = new Set();\n  for (const opt of options) {\n    for (const flag of [opt.short, opt.long].filter(Boolean)) {\n      if (seen.has(flag)) throw new Error(`duplicate flag ${flag}`);\n      seen.add(flag);\n    }\n    cmd.addOption(opt);\n  }\n}","typeGuard":"import { Option } from 'commander';\nfunction hasUniqueFlags(opts: Option[]): boolean {\n  const seen = new Set<string>();\n  return opts.every(o => [o.short, o.long].filter(Boolean).every(f => !seen.has(f) && (seen.add(f), true)));\n}","tryCatchPattern":null,"preventionTips":["Centralize option definitions to avoid cross-module collisions.","When merging commands from plugins, scan existing flags first.","Use distinct short flags for sibling commands (avoid universal -v/-h clashes)."],"tags":["commander","option","conflict","flag","configuration"],"analyzedSha":"ba6d13ddb4243e5913367734f8c159089ffe7834","analyzedAt":"2026-08-03T20:26:04.326Z","schemaVersion":2}