stablyai/orca · error · RuntimeClientError

invalid_argument

invalid_argument

Error message

Missing skill topic. Available topics: ${availableTopics}

What it means

Thrown by requireTopic when a skills command that needs a topic is invoked without a usable `--topic` — either the flag is absent, its value is a boolean (flag given no value), or it is an empty string. The message lists all currently available topic names so the user can pick one. This is a client-side precondition check before any guide resolution.

Source

Thrown at src/cli/handlers/skills.ts:45

  markdown: string
  fullMarkdown: string
  aliases: readonly string[]
}

function canonicalGuides(guides: readonly BundledSkillGuide[]): BundledSkillGuide[] {
  return [...guides].sort((left, right) =>
    left.name < right.name ? -1 : left.name > right.name ? 1 : 0
  )
}

function requireTopic(
  flags: Map<string, string | boolean>,
  guides: BundledSkillGuide[]
): BundledSkillGuide {
  const availableTopics = guides.map((guide) => guide.name).join(', ')
  const topic = flags.get('topic')
  if (typeof topic !== 'string' || topic.length === 0) {
    throw new RuntimeClientError(
      'invalid_argument',
      `Missing skill topic. Available topics: ${availableTopics}`
    )
  }
  // Why: installed stubs may retain an old topic forever, so aliases and canonical
  // names share one lookup table instead of being treated as transient CLI aliases.
  const guideByTopic = new Map<string, BundledSkillGuide>(
    guides.flatMap((guide) => [guide.name, ...guide.aliases].map((name) => [name, guide]))
  )
  const guide = guideByTopic.get(topic)
  if (!guide) {
    throw new RuntimeClientError(
      'invalid_argument',
      `Unknown skill topic "${topic}". Available topics: ${availableTopics}`
    )
  }
  return guide
}

View on GitHub (pinned to 1136503c6a)

Solutions

1. Pass `--topic <name>` using one of the names listed in the error message.
2. If the list is empty or wrong, your Orca build bundled no/different guides — update Orca or check the install.
3. In scripts, guard the flag: only emit `--topic` when the variable is non-empty.
4. Use a guide's alias if you only remember an alternate name (aliases resolve, but a missing topic does not).

Example fix

// before
orca skills show
TOPIC=
orca skills show --topic "$TOPIC"
// after
orca skills show --topic <name-from-available-list>
# in scripts: only pass --topic when set
[ -n "$TOPIC" ] && args+=(--topic "$TOPIC")

// requireTopic: flag must be a non-empty string
const topic = flags.get('topic')
const ok = typeof topic === 'string' && topic.length > 0
if (!ok) { /* print availableTopics, abort before calling the handler */ }

function isNonEmptyTopic(v: unknown): v is string {
  return typeof v === 'string' && v.trim().length > 0
}

try { await runSkillsTopic(flags) }
catch (e) {
  if (e instanceof RuntimeClientError && e.code === 'invalid_argument' && e.message.startsWith('Missing skill topic')) {
    // re-prompt for a topic from the listed available topics
  } else throw e
}

When it happens

Trigger: Running a skills topic-scoped subcommand (e.g. skills show/guide) with no `--topic`, with `--topic` alone and no value, or with `--topic ""`. The `flags.get('topic')` returns undefined or a non-string/empty and the guard fires.

Common situations: Forgetting the flag; assuming the first positional is the topic; an automation script that conditionally includes `--topic` only to leave it blank; shell quoting that collapses an empty variable to nothing.

Related errors

• invalid_argument
• invalid_environment
• invalid_argument
• invalid_argument
• --higher-is-better requires a metric key

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