stablyai/orca · error · RuntimeClientError

invalid_argument

invalid_argument

Error message

Unknown command: ${key}

What it means

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.

Source

Thrown at src/cli/dispatch.ts:43

        )
      }
      table.set(key, group)
    }
  }
  return table
}

const ROUTES = buildRoutes(HANDLER_GROUPS)

// Why: exposes only the canonical command keys (not the handler internals) so the
// registry-parity guard can check specs↔handlers without rebuilding the table.
export const HANDLER_COMMAND_KEYS: ReadonlySet<string> = new Set(ROUTES.keys())

export async function dispatch(commandPath: string[], ctx: HandlerContext): Promise<void> {
  const key = commandPath.join(' ')
  const group = ROUTES.get(key)
  if (!group) {
    throw new RuntimeClientError('invalid_argument', `Unknown command: ${key}`)
  }
  const handler = (await group.load())[key]
  // Why: the manifest key list is verified against the real exports in CI, so a
  // miss here means the group changed without the manifest — fail loudly.
  if (!handler) {
    throw new RuntimeClientError(
      'invalid_argument',
      `CLI handler group "${group.name}" does not export "${key}"`
    )
  }
  await handler(ctx)
}

export { buildRoutes as buildHandlerRoutes }

View on GitHub (pinned to 1136503c6a)

Solutions

1. Inspect the exported HANDLER_COMMAND_KEYS set to list every valid command key and re-issue with a matching one.
2. Check for typos or outdated command names against the current Orca version's help output.
3. 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.

Example fix

// before
dispatch(['acount', 'add'], ctx) // typo -> Unknown command: acount add

// after
dispatch(['account', 'add'], ctx)

import { HANDLER_COMMAND_KEYS } from './dispatch'

function assertKnownCommand(commandPath: string[]): void {
  const key = commandPath.join(' ')
  if (!HANDLER_COMMAND_KEYS.has(key)) {
    throw new Error(
      `Unknown command "${key}". Valid: ${[...HANDLER_COMMAND_KEYS].join(', ')}`
    )
  }
}

function isKnownCommand(commandPath: string[]): boolean {
  return HANDLER_COMMAND_KEYS.has(commandPath.join(' '))
}

try {
  await dispatch(commandPath, ctx)
} catch (e) {
  if (e instanceof RuntimeClientError && e.code === 'invalid_argument') {
    // surface valid keys from HANDLER_COMMAND_KEYS as a did-you-mean
  }
  throw e
}

When it happens

Trigger: 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.

Common situations: 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).

Related errors

• invalid_argument
• invalid_argument
• invalid_argument
• invalid_argument
• invalid_argument

AI-assisted analysis of stablyai/orca@1136503c6a (2026-08-12). Data as JSON: /api/errors/713424f6046fbfa8. Report an issue: GitHub.