stablyai/orca · error · RuntimeClientError

invalid_argument

invalid_argument

Error message

Missing required --index or --page

What it means

Thrown by the `tab switch` handler when neither --index nor --page is supplied. tab switch needs a target — either a numeric tab index (via getOptionalNonNegativeIntegerFlag) or a stable browser page id string (via getOptionalStringFlag). With both undefined/empty, there is nothing to switch to.

Source

Thrown at src/cli/handlers/browser-tab.ts:40

    printResult(result, json, (value) =>
      showProfile ? formatTabListWithProfiles(value, true) : formatTabList(value)
    )
  },
  'tab show': async ({ flags, client, cwd, json }) => {
    const target = await getBrowserCommandTarget(flags, cwd, client)
    const result = await client.call<BrowserTabShowResult>('browser.tabShow', target)
    printResult(result, json, formatTabShow)
  },
  'tab current': async ({ flags, client, cwd, json }) => {
    const worktree = await getBrowserWorktreeSelector(flags, cwd, client)
    const result = await client.call<BrowserTabCurrentResult>('browser.tabCurrent', { worktree })
    printResult(result, json, formatTabShow)
  },
  'tab switch': async ({ flags, client, cwd, json }) => {
    const index = getOptionalNonNegativeIntegerFlag(flags, 'index')
    const page = getOptionalStringFlag(flags, 'page')
    if (index === undefined && !page) {
      throw new RuntimeClientError('invalid_argument', 'Missing required --index or --page')
    }
    // Why: a stable browser page id is globally unique across Orca, so page-
    // targeted tab switches should match the rest of the --page command model:
    // global by default, with --worktree only acting as explicit validation.
    const target = await getBrowserCommandTarget(flags, cwd, client)
    // Why: --focus is an opt-in side effect. The renderer's handler is
    // worktree-scoped: it surfaces the browser pane only when the user is
    // already on the targeted worktree, otherwise it pre-stages silently.
    // Spread conditionally so the RPC payload stays shape-identical to the
    // pre-flag form when --focus is absent.
    const result = await client.call<BrowserTabSwitchResult>('browser.tabSwitch', {
      index,
      page,
      ...(flags.has('focus') ? { focus: true } : {}),
      ...target
    })
    printResult(result, json, (v) => `Switched to tab ${v.switched} (${v.browserPageId})`)
  },

View on GitHub (pinned to 1136503c6a)

Solutions

1. Add `--index <n>` (zero-based non-negative) or `--page <browserPageId>` to the command.
2. If you meant to focus the current tab rather than switch, use `tab current` instead.
3. Confirm the page id was copied from a `tab show`/`tab current` result and not truncated.

Example fix

// before
orca tab switch
// after
orca tab switch --index 2

function requireTabSwitchTarget(flags: Map<string, string | boolean>): void {
  const index = getOptionalNonNegativeIntegerFlag(flags, 'index')
  const page = getOptionalStringFlag(flags, 'page')
  if (index === undefined && !page) {
    throw new Error('tab switch requires --index <n> or --page <browserPageId>')
  }
}

When it happens

Trigger: Running `orca tab switch` with no target flags, or with only unrelated flags like --focus/--worktree. The `index === undefined && !page` guard fires before getBrowserCommandTarget is called.

Common situations: Assuming tab switch defaults to 'next' tab, forgetting the target after refactoring a script, or passing the page id into the wrong flag name.

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/806b2335f7125176. Report an issue: GitHub.