{"id":"9a6dd4819c69bd1a","repo":"tj/commander.js","slug":"to-add-an-option-object-use-addoption-instead-of","errorCode":null,"errorMessage":"To add an Option object use addOption() instead of option() or requiredOption()","messagePattern":"To add an Option object use addOption\\(\\) instead of option\\(\\) or requiredOption\\(\\)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/command.js","lineNumber":734,"sourceCode":"    if (option.envVar) {\n      this.on('optionEnv:' + oname, (val) => {\n        const invalidValueMessage = `error: option '${option.flags}' value '${val}' from env '${option.envVar}' is invalid.`;\n        handleOptionValue(val, invalidValueMessage, 'env');\n      });\n    }\n\n    return this;\n  }\n\n  /**\n   * Internal implementation shared by .option() and .requiredOption()\n   *\n   * @return {Command} `this` command for chaining\n   * @private\n   */\n  _optionEx(config, flags, description, fn, defaultValue) {\n    if (typeof flags === 'object' && flags instanceof Option) {\n      throw new Error(\n        'To add an Option object use addOption() instead of option() or requiredOption()',\n      );\n    }\n    const option = this.createOption(flags, description);\n    option.makeOptionMandatory(!!config.mandatory);\n    if (typeof fn === 'function') {\n      option.default(defaultValue).argParser(fn);\n    } else if (fn instanceof RegExp) {\n      // deprecated\n      const regex = fn;\n      fn = (val, def) => {\n        const m = regex.exec(val);\n        return m ? m[0] : def;\n      };\n      option.default(defaultValue).argParser(fn);\n    } else {\n      option.default(fn);\n    }","sourceCodeStart":716,"sourceCodeEnd":752,"githubUrl":"https://github.com/tj/commander.js/blob/ba6d13ddb4243e5913367734f8c159089ffe7834/lib/command.js#L716-L752","documentation":"Thrown by Command._optionEx() at lib/command.js:733-737 when an `Option` instance is passed to `.option()` or `.requiredOption()` instead of a flags string. Those methods expect a string flags argument and construct the Option internally via createOption; to register an already-built Option you must use addOption().","triggerScenarios":"`program.option(new Option('-d, --debug'))` or `program.requiredOption(myOption)`. The guard detects `typeof flags === 'object' && flags instanceof Option`.","commonSituations":"Switching from simple string-based options to the richer Option API (for .choices/.default/.env on the Option itself) but forgetting to change the registration method; copy-paste from addOption examples into option() calls; refactor that pre-builds Option objects for reuse.","solutions":["Use addOption(): `program.addOption(new Option('-d, --debug').default(false))`.","Or stay with the string form: `program.option('-d, --debug', 'enable debug')`."],"exampleFix":"// before (throws)\nprogram.option(new Option('-m, --mode <mode>').choices(['a','b']))\n\n// after\nprogram.addOption(new Option('-m, --mode <mode>').choices(['a','b']))","handlingStrategy":"type-guard","validationCode":"import { Option } from 'commander';\nfunction addEither(cmd, flagsOrOption, desc, fn, def) {\n  if (flagsOrOption instanceof Option) return cmd.addOption(flagsOrOption);\n  return cmd.option(flagsOrOption, desc, fn, def);\n}","typeGuard":"import { Option } from 'commander';\nfunction isOptionInstance(v: unknown): v is Option {\n  return v instanceof Option;\n}","tryCatchPattern":null,"preventionTips":["Use addOption() whenever you pre-build Option objects.","Keep .option()/.requiredOption() for the string-flags form.","Lint against passing objects to .option()."],"tags":["commander","option","api-misuse","configuration"],"analyzedSha":"ba6d13ddb4243e5913367734f8c159089ffe7834","analyzedAt":"2026-08-03T20:26:04.326Z","schemaVersion":2}