jackwener/OpenCLI · error · ArgumentError

${getErrorMessage(err)}

Error message

${getErrorMessage(err)}

What it means

In executeCommand, argument preparation (prepareCommandArgs) is wrapped in a try/catch: any failure during coercion/validation is rethrown as an ArgumentError whose message is the underlying error's message, except ArgumentError instances which pass through untouched. So this error surfaces the original argument-preparation failure text wrapped as an ArgumentError — it almost always traces back to a bad or missing CLI argument value, not to executeCommand itself.

Source

Thrown at src/execution.ts:226

    keepTab?: string;
    windowMode?: string;
    siteSession?: string;
    onTraceExport?: (trace: ObservationExportResult) => void;
  } = {},
): Promise<unknown> {
  // Resolve browser-only configuration before argument hooks or any browser
  // lifecycle setup. Non-browser commands must not be affected by browser
  // environment defaults, even when those defaults are invalid.
  const siteSession = shouldUseBrowserSession(cmd)
    ? resolveSiteSession(cmd, opts.siteSession)
    : null;

  let kwargs: CommandArgs;
  try {
    kwargs = opts.prepared ? rawKwargs : prepareCommandArgs(cmd, rawKwargs);
  } catch (err) {
    if (err instanceof ArgumentError) throw err;
    throw new ArgumentError(getErrorMessage(err));
  }

  const userTimeoutSec = readUserTimeoutSeconds(cmd, kwargs);
  // Propagate --timeout to the daemon transport so its per-command deadline
  // (and the derived extension/HTTP deadlines) honor the user's value instead
  // of the default. Set unconditionally so a previous command's value never
  // leaks into this one.
  setDaemonCommandTimeoutSeconds(userTimeoutSec);
  const traceMode = normalizeTraceMode(opts.trace);

  const hookCtx: HookContext = {
    command: fullName(cmd),
    args: kwargs,
    startedAt: Date.now(),
  };
  await emitHook('onBeforeExecute', hookCtx);

  let result: unknown;

View on GitHub (pinned to 49907e53dc)

Solutions

1. Read the wrapped message (it is the original error text) and fix the offending argument value or supply the missing required argument.
2. If invoking programmatically, pass opts.prepared = true only when you have already run prepareCommandArgs yourself; otherwise let the library prepare raw kwargs correctly.
3. Validate your kwargs against the command's argument definitions (names, required flags, choices) before calling executeCommand.
4. Check for recent argument-definition changes (renamed/now-required args) if this worked in a previous version.

Example fix

// before
await executeCommand(cmd, { mode: 'faast' }); // ArgumentError: must be one of: fast, slow

// after
await executeCommand(cmd, { mode: 'fast' });

function preValidateKwargs(cmd, rawKwargs) {
  for (const argDef of cmd.args ?? []) {
    if (argDef.required && rawKwargs[argDef.name] === undefined && argDef.default === undefined) {
      throw new Error(`Missing required argument '${argDef.name}' for '${cmd.name}'`);
    }
  }
}

function isArgumentError(err) {
  return err instanceof ArgumentError;
}

try {
  await executeCommand(cmd, rawKwargs);
} catch (err) {
  if (err instanceof ArgumentError) {
    console.error(`Invalid arguments for '${cmd.name}': ${err.message}`);
    process.exitCode = 2;
  } else {
    throw err;
  }
}

When it happens

Trigger: Calling executeCommand (directly or via result/error/thrown/rejection helpers) with rawKwargs that fail prepareCommandArgs when opts.prepared is not set — e.g. missing required arguments, values failing coercion/parsing, or values failing the choices check from coerceAndValidateArgs.

Common situations: Programmatic callers passing unprepared kwargs objects (missing required fields or wrong types); shell scripts passing empty or malformed flag values; users of the result/error helper APIs forgetting to pre-prepare arguments; version changes where an argument became required or gained choices.

Related errors

• <train-no> "${trainNo}" does not look like a 12306 internal
• --from station must not be empty
• --to station must not be empty
• --seat-types must contain only 12306 seat letters/digits (A-
• --from and --to must differ; both resolved to ${fromStation.

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/5c79548524098e84. Report an issue: GitHub.