tj/commander.js · error · Error

option creation failed due to no flags found in '${flags}'.

Error message

option creation failed due to no flags found in '${flags}'.

What it means

Thrown by splitOptionFlags() when, after processing every token, neither a short flag nor a long flag was found (both are undefined). This means the flags string contained no dash-prefixed token at all, e.g. an empty string, a bare placeholder like '<value>', or free text. Every Option must declare at least one flag, so this is rejected at construction.

Source

Thrown at lib/option.js:372

    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

Include at least one flag token: new Option('-v <value>') or new Option('--name <value>').
Double-check argument order: the signature is new Option(flags, description).
If flags come from config, fail fast on empty/missing values before constructing the Option.

Example fix

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

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

Defensive patterns

Strategy: validation

Validate before calling

// An Option must declare at least one flag token.
function hasAnyFlag(flags) {
  return String(flags).split(/[ |,]+/).some((t) => /^-[^-]/.test(t) || /^--[^-]/.test(t));
}
function assertHasFlag(flags) {
  if (!hasAnyFlag(flags)) {
    throw new Error(`Option flags must include at least one flag (got '${flags}')`);
  }
}
// usage: assertHasFlag(flags); new Option(flags, description);

Prevention

The Option constructor signature is new Option(flags, description); always pass a real flag first.
Reject empty/undefined flag values from config before constructing an Option.
Include at least '-x' or '--name'; a bare placeholder like '<value>' is not a flag.

When it happens

Trigger: Constructing new Option(''), new Option('<value>'), new Option('description only'), or new Option(undefined) coerced to the string 'undefined' (which has no leading dash). Also when a variable meant to hold the flag name is empty.

Common situations: Passing only the value placeholder and forgetting the flag; passing the description as the first arg and the flag nowhere; empty config values feeding the flags string; refactors that moved the flag into a different argument.

Related errors

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