{"record":{"id":"713424f6046fbfa8","repo":"stablyai/orca","slug":"invalid-argument-713424","errorCode":"invalid_argument","errorMessage":"Unknown command: ${key}","messagePattern":"Unknown command: (.+?)","errorType":"validation","errorClass":"RuntimeClientError","httpStatus":null,"severity":"error","filePath":"src/cli/dispatch.ts","lineNumber":43,"sourceCode":"        )\n      }\n      table.set(key, group)\n    }\n  }\n  return table\n}\n\nconst ROUTES = buildRoutes(HANDLER_GROUPS)\n\n// Why: exposes only the canonical command keys (not the handler internals) so the\n// registry-parity guard can check specs↔handlers without rebuilding the table.\nexport const HANDLER_COMMAND_KEYS: ReadonlySet<string> = new Set(ROUTES.keys())\n\nexport async function dispatch(commandPath: string[], ctx: HandlerContext): Promise<void> {\n  const key = commandPath.join(' ')\n  const group = ROUTES.get(key)\n  if (!group) {\n    throw new RuntimeClientError('invalid_argument', `Unknown command: ${key}`)\n  }\n  const handler = (await group.load())[key]\n  // Why: the manifest key list is verified against the real exports in CI, so a\n  // miss here means the group changed without the manifest — fail loudly.\n  if (!handler) {\n    throw new RuntimeClientError(\n      'invalid_argument',\n      `CLI handler group \"${group.name}\" does not export \"${key}\"`\n    )\n  }\n  await handler(ctx)\n}\n\nexport { buildRoutes as buildHandlerRoutes }\n","sourceCodeStart":25,"sourceCodeEnd":58,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/cli/dispatch.ts#L25-L58","documentation":"Thrown by dispatch() when the joined command path is not present in the ROUTES table built from HANDLER_GROUPS. The router maps a space-joined key (e.g. 'account add') to a lazily-loaded handler group; an unknown key means no handler was ever registered for that command shape. It surfaces as code 'invalid_argument' so callers can distinguish a bad command path from a runtime execution failure.","triggerScenarios":"Calling dispatch(commandPath, ctx) where commandPath.join(' ') is not one of the keys exported by any HandlerGroup in HANDLER_GROUPS. Typing a subcommand that does not exist, misspelling a known command, or passing an empty/stale commandPath array.","commonSituations":"User runs a CLI alias or typo (e.g. 'orca acount add'), a script calls a command that was renamed/removed in a newer Orca version, or a handler group manifest forgot to list a newly added command key (caught by CI parity guard but visible at runtime if bypassed).","solutions":["Inspect the exported HANDLER_COMMAND_KEYS set to list every valid command key and re-issue with a matching one.","Check for typos or outdated command names against the current Orca version's help output.","If adding a new command, register its key in the relevant handler group's `keys` array in handler-group-manifest so buildRoutes picks it up."],"exampleFix":"// before\ndispatch(['acount', 'add'], ctx) // typo -> Unknown command: acount add\n\n// after\ndispatch(['account', 'add'], ctx)","handlingStrategy":"validation","validationCode":"import { HANDLER_COMMAND_KEYS } from './dispatch'\n\nfunction assertKnownCommand(commandPath: string[]): void {\n  const key = commandPath.join(' ')\n  if (!HANDLER_COMMAND_KEYS.has(key)) {\n    throw new Error(\n      `Unknown command \"${key}\". Valid: ${[...HANDLER_COMMAND_KEYS].join(', ')}`\n    )\n  }\n}","typeGuard":"function isKnownCommand(commandPath: string[]): boolean {\n  return HANDLER_COMMAND_KEYS.has(commandPath.join(' '))\n}","tryCatchPattern":"try {\n  await dispatch(commandPath, ctx)\n} catch (e) {\n  if (e instanceof RuntimeClientError && e.code === 'invalid_argument') {\n    // surface valid keys from HANDLER_COMMAND_KEYS as a did-you-mean\n  }\n  throw e\n}","preventionTips":["Build command paths from a typed union of known keys, not free strings.","In wrappers, validate against HANDLER_COMMAND_KEYS before dispatch.","Keep the handler-group manifest in sync so CI parity guards catch missing keys."],"tags":["cli","routing","invalid-argument"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}