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 short flags

What it means

Thrown by splitOptionFlags() when, after consuming the first valid short flag, another token still matches the short-flag shape /^-[^-]$/. Commander allows at most one short flag per option, so a second single-dash-single-char token is rejected as 'too many short flags'. Raised synchronously during `new Option(flags)`.

Source

Thrown at lib/option.js:362

  // This is the supported way to have a shortish option flag.
  if (!shortFlag && longFlagExp.test(flagParts[0])) {
    shortFlag = longFlag;
    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

Keep only one short flag: new Option('-f <value>').
Express the second name as a long alias: new Option('-f, --fg <value>').
Split the behavior into two separate Option instances if both shorts are genuinely needed.

Example fix

// before
new Option('-f, -g <value>');

// after
new Option('-f, --fg <value>');

Defensive patterns

Strategy: validation

Validate before calling

// Reuses the same rule mirror as error 23; focused check for too-many-shorts.
function previewOptionFlagsError(flags) {
  const shortFlagExp = /^-[^-]$/;
  const longFlagExp = /^--[^-]/;
  const flagParts = String(flags).split(/[ |,]+/).concat('guard');
  let shortFlag, longFlag;
  if (shortFlagExp.test(flagParts[0])) shortFlag = flagParts.shift();
  if (longFlagExp.test(flagParts[0])) longFlag = flagParts.shift();
  if (!shortFlag && shortFlagExp.test(flagParts[0])) shortFlag = flagParts.shift();
  if (!shortFlag && longFlagExp.test(flagParts[0])) { shortFlag = longFlag; longFlag = flagParts.shift(); }
  if (flagParts[0].startsWith('-')) {
    const u = flagParts[0];
    if (/^-[^-][^-]/.test(u)) return `short flag must be one dash + one char: '${u}'`;
    if (shortFlagExp.test(u)) return `too many short flags: '${u}'`;
    if (longFlagExp.test(u)) return `too many long flags: '${u}'`;
    return `unrecognised flag format: '${u}'`;
  }
  if (shortFlag === undefined && longFlag === undefined) return `no flags found in '${flags}'`;
  return null;
}
// Quick dedicated check for two-or-more short flags:
function hasMultipleShortFlags(flags) {
  return (String(flags).match(/(^|[, ])-[^- ](?!\S*\.)/g) || []).length > 1;
}

Prevention

An option may have at most one short flag; give additional names as long aliases.
Use the shared previewOptionFlagsError helper to validate generated flags.
Unit-test option construction to catch this at build time, not runtime.

When it happens

Trigger: Constructing new Option('-f, -g <value>'), new Option('-a -b'), or any flags string that lists two or more distinct short flags separated by space/comma.

Common situations: Trying to give an option two short aliases; merging two options into one; copy-paste that left an extra short flag; misreading the docs and assuming multiple shorts are allowed like multiple longs are.

Related errors

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