{"record":{"id":"5c79548524098e84","repo":"jackwener/OpenCLI","slug":"geterrormessage-err","errorCode":null,"errorMessage":"${getErrorMessage(err)}","messagePattern":"\\$\\{getErrorMessage\\(err\\)\\}","errorType":"validation","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"src/execution.ts","lineNumber":226,"sourceCode":"    keepTab?: string;\n    windowMode?: string;\n    siteSession?: string;\n    onTraceExport?: (trace: ObservationExportResult) => void;\n  } = {},\n): Promise<unknown> {\n  // Resolve browser-only configuration before argument hooks or any browser\n  // lifecycle setup. Non-browser commands must not be affected by browser\n  // environment defaults, even when those defaults are invalid.\n  const siteSession = shouldUseBrowserSession(cmd)\n    ? resolveSiteSession(cmd, opts.siteSession)\n    : null;\n\n  let kwargs: CommandArgs;\n  try {\n    kwargs = opts.prepared ? rawKwargs : prepareCommandArgs(cmd, rawKwargs);\n  } catch (err) {\n    if (err instanceof ArgumentError) throw err;\n    throw new ArgumentError(getErrorMessage(err));\n  }\n\n  const userTimeoutSec = readUserTimeoutSeconds(cmd, kwargs);\n  // Propagate --timeout to the daemon transport so its per-command deadline\n  // (and the derived extension/HTTP deadlines) honor the user's value instead\n  // of the default. Set unconditionally so a previous command's value never\n  // leaks into this one.\n  setDaemonCommandTimeoutSeconds(userTimeoutSec);\n  const traceMode = normalizeTraceMode(opts.trace);\n\n  const hookCtx: HookContext = {\n    command: fullName(cmd),\n    args: kwargs,\n    startedAt: Date.now(),\n  };\n  await emitHook('onBeforeExecute', hookCtx);\n\n  let result: unknown;","sourceCodeStart":208,"sourceCodeEnd":244,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/src/execution.ts#L208-L244","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the wrapped message (it is the original error text) and fix the offending argument value or supply the missing required argument.","If invoking programmatically, pass opts.prepared = true only when you have already run prepareCommandArgs yourself; otherwise let the library prepare raw kwargs correctly.","Validate your kwargs against the command's argument definitions (names, required flags, choices) before calling executeCommand.","Check for recent argument-definition changes (renamed/now-required args) if this worked in a previous version."],"exampleFix":"// before\nawait executeCommand(cmd, { mode: 'faast' }); // ArgumentError: must be one of: fast, slow\n\n// after\nawait executeCommand(cmd, { mode: 'fast' });","handlingStrategy":"try-catch","validationCode":"function preValidateKwargs(cmd, rawKwargs) {\n  for (const argDef of cmd.args ?? []) {\n    if (argDef.required && rawKwargs[argDef.name] === undefined && argDef.default === undefined) {\n      throw new Error(`Missing required argument '${argDef.name}' for '${cmd.name}'`);\n    }\n  }\n}","typeGuard":"function isArgumentError(err) {\n  return err instanceof ArgumentError;\n}","tryCatchPattern":"try {\n  await executeCommand(cmd, rawKwargs);\n} catch (err) {\n  if (err instanceof ArgumentError) {\n    console.error(`Invalid arguments for '${cmd.name}': ${err.message}`);\n    process.exitCode = 2;\n  } else {\n    throw err;\n  }\n}","preventionTips":["Validate required arguments and choices before calling executeCommand.","Only set opts.prepared = true when you have genuinely run prepareCommandArgs yourself.","Log the full ArgumentError message — it contains the underlying preparation failure verbatim.","Review argument definitions after upgrading; requirements may have changed."],"tags":["argument-validation","cli","error-wrapping"],"backgroundTag":"argument-preparation-failed","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}