tj/commander.js · error · Error

To add an Option object use addOption() instead of option()

Error message

To add an Option object use addOption() instead of option() or requiredOption()

What it means

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().

Source

Thrown at lib/command.js:734

    if (option.envVar) {
      this.on('optionEnv:' + oname, (val) => {
        const invalidValueMessage = `error: option '${option.flags}' value '${val}' from env '${option.envVar}' is invalid.`;
        handleOptionValue(val, invalidValueMessage, 'env');
      });
    }

    return this;
  }

  /**
   * Internal implementation shared by .option() and .requiredOption()
   *
   * @return {Command} `this` command for chaining
   * @private
   */
  _optionEx(config, flags, description, fn, defaultValue) {
    if (typeof flags === 'object' && flags instanceof Option) {
      throw new Error(
        'To add an Option object use addOption() instead of option() or requiredOption()',
      );
    }
    const option = this.createOption(flags, description);
    option.makeOptionMandatory(!!config.mandatory);
    if (typeof fn === 'function') {
      option.default(defaultValue).argParser(fn);
    } else if (fn instanceof RegExp) {
      // deprecated
      const regex = fn;
      fn = (val, def) => {
        const m = regex.exec(val);
        return m ? m[0] : def;
      };
      option.default(defaultValue).argParser(fn);
    } else {
      option.default(fn);
    }

View on GitHub (pinned to ba6d13ddb4)

Solutions

1. Use addOption(): `program.addOption(new Option('-d, --debug').default(false))`.
2. Or stay with the string form: `program.option('-d, --debug', 'enable debug')`.

Example fix

// before (throws)
program.option(new Option('-m, --mode <mode>').choices(['a','b']))

// after
program.addOption(new Option('-m, --mode <mode>').choices(['a','b']))

import { Option } from 'commander';
function addEither(cmd, flagsOrOption, desc, fn, def) {
  if (flagsOrOption instanceof Option) return cmd.addOption(flagsOrOption);
  return cmd.option(flagsOrOption, desc, fn, def);
}

import { Option } from 'commander';
function isOptionInstance(v: unknown): v is Option {
  return v instanceof Option;
}

When it happens

Trigger: `program.option(new Option('-d, --debug'))` or `program.requiredOption(myOption)`. The guard detects `typeof flags === 'object' && flags instanceof Option`.

Common situations: 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.

Related errors

• Cannot add option '${option.flags}'${this._name && ` to comm
• Command passed to .addCommand() must have a name - specify t
• only the last argument can be variadic '${previousArgument.n
• a default value for a required argument is never used: '${ar
• Unexpected value for event passed to hook : '${event}'. Expe

AI-assisted analysis of tj/commander.js@ba6d13ddb4 (2026-08-03). Data as JSON: /data/errors/9a6dd4819c69bd1a.json. Report an issue: GitHub.