tj/commander.js · error · Error

passThroughOptions cannot be used for '${this._name}' withou

Error message

passThroughOptions cannot be used for '${this._name}' without turning on enablePositionalOptions for parent command(s)

What it means

Thrown by Command._checkForBrokenPassThrough() at lib/command.js:876-886 when a subcommand has passThroughOptions enabled but its parent chain does not have enablePositionalOptions on. passThrough means unknown options are forwarded as positional tokens to the subcommand; that only works if the parent is in positional mode, otherwise the tokens would be consumed/misinterpreted upstream.

Source

Thrown at lib/command.js:882

   * @return {Command} `this` command for chaining
   */
  passThroughOptions(passThrough = true) {
    this._passThroughOptions = !!passThrough;
    this._checkForBrokenPassThrough();
    return this;
  }

  /**
   * @private
   */

  _checkForBrokenPassThrough() {
    if (
      this.parent &&
      this._passThroughOptions &&
      !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) {

View on GitHub (pinned to ba6d13ddb4)

Solutions

Enable positional options on the parent: `program.enablePositionalOptions();` before registering/calling the child.
Ensure every ancestor in the chain has enablePositionalOptions if the subcommand uses passThrough.
If passThrough was unintended, remove the `.passThroughOptions()` call.

Example fix

// before (throws)
const child = new Command('child').passThroughOptions();
program.addCommand(child);

// after
program.enablePositionalOptions();
program.addCommand(child);

Defensive patterns

Strategy: validation

Validate before calling

function enablePassThrough(program, child) {
  if (!program._enablePositionalOptions) {
    throw new Error('Call program.enablePositionalOptions() before passThroughOptions on a child');
  }
  child.passThroughOptions();
}

Prevention

Always set program.enablePositionalOptions() first if any child uses passThroughOptions.
Configure the root command before adding subcommands.
Add a smoke test that builds the full command tree to surface ordering bugs at startup.

When it happens

Trigger: `program.command('child').passThroughOptions()` without first calling `program.enablePositionalOptions()`. The check walks this.parent._enablePositionalOptions and throws if falsy. Also triggered retroactively when addCommand registers a child whose passThroughOptions was set before the parent enabled positional.

Common situations: Building a 'passthrough' wrapper command that delegates flags to a downstream tool (git-style); enabling passThrough on a subcommand during a refactor without updating the root; ordering bug where .passThroughOptions() is called before .enablePositionalOptions() on the parent.

Related errors

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