stablyai/orca · error · BrowserError

browser_no_tab

browser_no_tab

Error message

No browser tab is open. Use the Orca UI to open a browser tab first.

What it means

getActiveGuest() is the private resolver called by every CDP command to find which WebContents to operate on. If no tab has been explicitly selected (activeWebContentsId is null) and the registry is empty, there is no tab to target. The message directs the user to open a browser tab via the Orca UI before issuing automation commands. Every public method (click, fill, screenshot, etc.) hits this path.

Source

Thrown at src/main/browser/cdp-bridge.ts:1035

  onTabChanged(webContentsId: number): void {
    this.activeWebContentsId = webContentsId
  }

  // ── Private helpers ──

  private getActiveGuest(): Electron.WebContents {
    if (this.activeWebContentsId !== null) {
      const guest = webContents.fromId(this.activeWebContentsId)
      if (guest && !guest.isDestroyed()) {
        return guest
      }
      // Why: webContentsId goes stale after a process swap; fall through to auto-select since the tab may have a new id.
      this.activeWebContentsId = null
    }

    const tabs = [...this.getRegisteredTabs()]
    if (tabs.length === 0) {
      throw new BrowserError(
        'browser_no_tab',
        'No browser tab is open. Use the Orca UI to open a browser tab first.'
      )
    }
    if (tabs.length === 1) {
      this.activeWebContentsId = tabs[0][1]
    } else {
      throw new BrowserError(
        'browser_no_tab',
        "Multiple browser tabs are open. Run 'orca tab list' and 'orca tab switch --index <n>' to select one."
      )
    }

    const guest = webContents.fromId(this.activeWebContentsId!)
    if (!guest || guest.isDestroyed()) {
      this.activeWebContentsId = null
      throw new BrowserError(
        'browser_debugger_detached',

View on GitHub (pinned to 1136503c6a)

Solutions

Open a browser tab in the Orca UI or via the tab-creation API before issuing commands.
Check bridge.tabList().tabs.length === 0 before issuing commands and create a tab if needed.
Guard agent workflows with a 'no tab open' check at the top.

Example fix

// before
await bridge.click('ref1')

// after
if (bridge.tabList().tabs.length === 0) {
  await bridge.goto('https://example.com') // or createTab
}
await bridge.click('ref1')

Defensive patterns

Strategy: validation

Validate before calling

if (bridge.tabList().tabs.length === 0) {
  throw new Error('No browser tab is open. Open a tab first.')
}
await bridge.click(ref)

Try / catch

try {
  await bridge.click(ref)
} catch (e) {
  if (e instanceof BrowserError && e.code === 'browser_no_tab' && /No browser tab/.test(e.message)) {
    // create or open a tab, then retry
  }
  throw e
}

Prevention

Check tabList().tabs.length > 0 before issuing any browser command.
In agent workflows, open a tab as the first step before any automation.
Handle browser_no_tab as a recoverable error by prompting the user to open a tab.

When it happens

Trigger: Calling any browser-automation command before any browser tab has been opened in the current workspace; all tabs were closed and the registry is now empty.

Common situations: Agent attempts browser actions in a fresh workspace with no tab open; all tabs were closed during a session; remote Orca server with no browser tab created yet.

Related errors

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