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}'
- 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')

What it means

Thrown by the private splitOptionFlags() helper at Option construction when a leftover flag token matches /^-[^-][^-]/: a single dash followed by two or more non-dash characters (e.g. '-ab'). A short flag must be exactly one dash plus one character; multi-character names must use a double dash. The error message explicitly suggests either a single-char short flag or a '--long, --long-alias' pair.

Source

Thrown at lib/option.js:355

  // Normal is short and/or long.
  if (shortFlagExp.test(flagParts[0])) shortFlag = flagParts.shift();
  if (longFlagExp.test(flagParts[0])) longFlag = flagParts.shift();
  // Long then short. Rarely used but fine.
  if (!shortFlag && shortFlagExp.test(flagParts[0]))
    shortFlag = flagParts.shift();
  // Allow two long flags, like '--ws, --workspace'
  // 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}'.`,

View on GitHub (pinned to ba6d13ddb4)

Solutions

Use a double dash for multi-character names: new Option('--ws <value>').
Or use a single-character short flag: new Option('-w <value>').
For an alias pair use two long flags: new Option('--ws, --workspace <value>').
If flags are generated dynamically, validate them with the helper in validationCode before constructing the Option.

Example fix

// before
new Option('-ws <value>');

// after
new Option('--ws <value>');

Defensive patterns

Strategy: validation

Validate before calling

// Mirrors Commander's splitOptionFlags rules; returns an error string or null.
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}' (use --long instead)`;
    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;
}
// usage: const e = previewOptionFlagsError('-ws'); if (e) throw new Error(e);

Prevention

Short flags are strictly one dash + one character; never two chars after a single dash.
For a 'shortish' two-letter option use the two-long-flags form: '--ws, --workspace'.
When flags are generated from config keys, run previewOptionFlagsError before constructing Option.
Add a unit test that constructs every option your CLI declares.

When it happens

Trigger: Constructing new Option('-ws <value>'), new Option('-ab'), or any flags string containing a token like '-xx'. Also when intending the supported 'shortish' pattern ('--ws, --workspace') but mistakenly writing '-ws, --workspace'.

Common situations: Wanting a two-letter shortcut and not realizing short flags are strictly one char; copying flag spellings from another tool; auto-generating flags from config keys by prepending a single dash.

Related errors

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