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}'
- unrecognised flag format

What it means

Thrown by splitOptionFlags() when a leftover token starts with '-' but matches none of the recognized shapes: not /^-[^-][^-]/ (handled by error 23), not /^-[^-]$/ (a valid short, error 24), and not /^--[^-]/ (a valid long, error 25). Examples are a lone '-', a bare '--', or '---foo'. It is the catch-all 'unrecognised flag format' branch, raised at Option construction.

Source

Thrown at lib/option.js:368

  // 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

Provide a well-formed flag: a single-char short ('-x') or a double-dash long ('--name').
If flags are assembled from variables, guard against empty/whitespace-only names before adding dashes.
Strip any stray '--' or lone '-' tokens from generated flag strings before constructing the Option.

Example fix

// before
new Option('-');

// after
new Option('-x');

Defensive patterns

Strategy: validation

Validate before calling

// Detect dash-prefixed tokens that are not valid short or long flags.
function findUnrecognisedFlag(flags) {
  const shortFlagExp = /^-[^-]$/;
  const longFlagExp = /^--[^-]/;
  for (const tok of String(flags).split(/[ |,]+/)) {
    if (!tok.startsWith('-')) continue;
    if (/^-[^-][^-]/.test(tok) || shortFlagExp.test(tok) || longFlagExp.test(tok)) continue;
    return tok; // e.g. '-', '--', '---foo'
  }
  return null;
}
// usage: const bad = findUnrecognisedFlag(flags); if (bad) throw new Error(`bad flag '${bad}'`);

Prevention

Every dash-prefixed token must be either '-x' or '--name'; lone dashes or bare '--' are invalid.
When building flags by concatenation, never emit '-' + '' (empty name).
Strip stray '--' separators from generated flag lists before constructing Option.

When it happens

Trigger: Constructing new Option('-'), new Option('--'), new Option('---foo'), or new Option('-- <value>') where the token is only dashes. Also any malformed dash-prefixed token produced by string concatenation bugs.

Common situations: Building flags dynamically and leaving an empty name after the dash (e.g. '-' + ''); stray '--' separator tokens accidentally included in the flags string; copy-paste artifacts; off-by-one in template literals producing '---'.

Related errors

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