tj/commander.js · error · Error

option creation failed due to '${unsupportedFlag}' in option

Error message

option creation failed due to '${unsupportedFlag}' in option flags '${flags}'
- too many long flags

What it means

Thrown by splitOptionFlags() when a third long flag is encountered. Commander allows up to two long flags per option (the supported '--ws, --workspace' alias pattern, where the first becomes this.short and the second this.long), but a third long token matches longFlagExp /^--[^-]/ and is rejected as 'too many long flags'. Raised at Option construction.

Source

Thrown at lib/option.js:365

    longFlag = flagParts.shift();
  }

  // Check for unprocessed flag. Fail noisily rather than silently ignore.
  if (flagParts[0].startsWith('-')) {
    const unsupportedFlag = flagParts[0];
    const baseError = `option creation failed due to '${unsupportedFlag}' in option flags '${flags}'`;
    if (/^-[^-][^-]/.test(unsupportedFlag))
      throw new Error(
        `${baseError}
- a short flag is a single dash and a single character
  - either use a single dash and a single character (for a short flag)
  - or use a double dash for a long option (and can have two, like '--ws, --workspace')`,
      );
    if (shortFlagExp.test(unsupportedFlag))
      throw new Error(`${baseError}
- too many short flags`);
    if (longFlagExp.test(unsupportedFlag))
      throw new Error(`${baseError}
- too many long flags`);

    throw new Error(`${baseError}
- unrecognised flag format`);
  }
  if (shortFlag === undefined && longFlag === undefined)
    throw new Error(
      `option creation failed due to no flags found in '${flags}'.`,
    );

  return { shortFlag, longFlag };
}

View on GitHub (pinned to ba6d13ddb4)

Solutions

Reduce to at most two long flags: new Option('--a, --b').
Move extra aliases into a separate Option or document them in the description.
If many names must map to one action, handle them as separate options that set the same value in the action handler.

Example fix

// before
new Option('--a, --b, --c');

// after
new Option('--a, --b');

Defensive patterns

Strategy: validation

Validate before calling

// Focused check: count long flags; >2 is rejected by Commander.
function countLongFlags(flags) {
  return (String(flags).match(/(^|[, ])--[^- ,]/g) || []).length;
}
function assertLongFlagsOk(flags) {
  if (countLongFlags(flags) > 2) {
    throw new Error(`too many long flags in '${flags}' (max 2, e.g. '--ws, --workspace')`);
  }
}
// usage: assertLongFlagsOk('--a, --b, --c');

Prevention

Commander allows at most two long flags per option (an alias pair); a third throws.
If you need many names, map them to one value in your action handler instead of one Option.
Validate generated flag strings with countLongFlags before constructing Option.

When it happens

Trigger: Constructing new Option('--a, --b, --c'), new Option('--ws, --workspace, --work'), or any flags string listing three or more double-dash tokens.

Common situations: Wanting three or more aliases for one option; auto-generating synonyms from config; misunderstanding the two-long-flags alias feature and assuming it is unlimited.

Related errors

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