tj/commander.js · error · Error

call .storeOptionsAsProperties() before adding options

Error message

call .storeOptionsAsProperties() before adding options

What it means

Thrown by Command.storeOptionsAsProperties() at lib/command.js:897-899 when called after options have already been added. The storage mode (properties on `this` vs internal _optionValues map) affects how every option is registered and read, so it must be configured before any .option()/addOption() call.

Source

Thrown at lib/command.js:898

      !this.parent._enablePositionalOptions
    ) {
      throw new Error(
        `passThroughOptions cannot be used for '${this._name}' without turning on enablePositionalOptions for parent command(s)`,
      );
    }
  }

  /**
   * Whether to store option values as properties on command object,
   * or store separately (specify false). In both cases the option values can be accessed using .opts().
   *
   * @param {boolean} [storeAsProperties=true]
   * @return {Command} `this` command for chaining
   */

  storeOptionsAsProperties(storeAsProperties = true) {
    if (this.options.length) {
      throw new Error('call .storeOptionsAsProperties() before adding options');
    }
    if (Object.keys(this._optionValues).length) {
      throw new Error(
        'call .storeOptionsAsProperties() before setting option values',
      );
    }
    this._storeOptionsAsProperties = !!storeAsProperties;
    return this;
  }

  /**
   * Retrieve option value.
   *
   * @param {string} key
   * @return {object} value
   */

  getOptionValue(key) {

View on GitHub (pinned to ba6d13ddb4)

Solutions

Move the call to the very top of configuration, before any .option()/addOption(): `program.storeOptionsAsProperties(false).option(...)`.
Or stop using storeOptionsAsProperties entirely — modern Commander defaults to the _optionValues map and .opts() access, which is recommended.

Example fix

// before (throws)
program.option('-d, --debug', 'debug').storeOptionsAsProperties();

// after
program.storeOptionsAsProperties().option('-d, --debug', 'debug');

Defensive patterns

Strategy: validation

Validate before calling

function configureStorage(cmd, asProperties) {
  if (cmd.options.length) {
    throw new Error('storeOptionsAsProperties must be called before adding options');
  }
  return cmd.storeOptionsAsProperties(asProperties);
}

Prevention

Decide storage mode at the very top of setup, before any .option() call.
Prefer the default (false) and use .opts().
Encapsulate program construction in a factory so ordering is enforced.

When it happens

Trigger: `program.option('-d','debug').storeOptionsAsProperties()` — options array is non-empty when the method runs, tripping the guard. Order-of-operations bug in setup code.

Common situations: Migrating from older Commander where storing as properties was the default; toggling storage mode mid-setup; calling storeOptionsAsProperties inside a factory that runs after options were declared elsewhere.

Related errors

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