stablyai/orca · error · BrowserError

browser_eval_error

browser_eval_error

Error message

${exceptionDetails.exception?.description ?? exceptionDetails.text}

What it means

Thrown by evaluate() after a CDP `Runtime.evaluate` call returns `exceptionDetails` — the JavaScript expression was delivered to the page and executed, but it threw a runtime exception inside the browser context. The message is the exception's description (preferred) or the generic exceptionDetails.text. This is distinct from a transport/protocol failure: the eval ran, the page's JS threw.

Source

Thrown at src/main/browser/agent-browser-bridge.ts:1575

  ): Promise<BrowserEvalResult> {
    return this.enqueueTargetedCommand(
      worktreeId,
      browserPageId,
      async (_sessionName, target) => {
        const wc = this.requireTargetWebContents(target)
        let releaseDebugger = (): void => {}
        try {
          releaseDebugger = acquireElectronDebugger(wc).release
          const { result, exceptionDetails } = (await wc.debugger.sendCommand('Runtime.evaluate', {
            expression,
            returnByValue: true,
            awaitPromise: true
          })) as {
            result: { value?: unknown; description?: string }
            exceptionDetails?: { text: string; exception?: { description?: string } }
          }
          if (exceptionDetails) {
            throw new BrowserError(
              'browser_eval_error',
              exceptionDetails.exception?.description ?? exceptionDetails.text
            )
          }

          const currentTarget = this.resolveCommandTarget(worktreeId, target.browserPageId)
          if (currentTarget.webContentsId !== target.webContentsId) {
            throw new BrowserError(
              'browser_tab_changed',
              `Browser page ${target.browserPageId} changed while evaluating; retry the command`
            )
          }
          return {
            result:
              result.value !== undefined
                ? typeof result.value === 'object' && result.value !== null
                  ? JSON.stringify(result.value)
                  : String(result.value)

View on GitHub (pinned to 1136503c6a)

Solutions

Read the exception description in the message — it contains the JS stack and error type from the page.
Wrap the eval expression in try/catch inside the JS itself so it returns a descriptive string instead of throwing.
Add null/existence guards in the expression (e.g. `document.querySelector('#x')?.textContent ?? 'not found'`).
Verify the expression runs in the page's main world context and not an isolated world where page globals are absent.

Example fix

// before
await bridge.evaluate('document.querySelector("#missing").value')
// after
await bridge.evaluate('(document.querySelector("#missing")?.value) ?? null')

Defensive patterns

Strategy: try-catch

Validate before calling

// validate expression syntax before sending to CDP
try { new Function(expression) } catch (e) { throw new Error(`Invalid eval expression: ${e.message}`) }

Try / catch

try {
  return await bridge.evaluate(expression, worktreeId, browserPageId)
} catch (e) {
  if (e instanceof BrowserError && e.code === 'browser_eval_error') {
    // the expression threw inside the page — fix the expression, don't retry blindly
    throw new Error(`Page eval failed: ${e.message}`)
  }
  throw e
}

Prevention

Wrap eval expressions in optional chaining and nullish coalescing to avoid null derefs
Validate expression syntax client-side before sending to CDP
Return JSON-safe primitives from eval expressions to avoid serialization issues
Use try/catch inside the eval expression itself and return an error string

When it happens

Trigger: Calling evaluate(expression) where `expression` is syntactically valid JS that throws at runtime — e.g. accessing a property of undefined, calling a non-function, a rejected awaited promise (awaitPromise: true surfaces rejection), or referencing a variable not in the page's scope. CDP populates exceptionDetails.exception.description with the JS stack.

Common situations: Agent-generated eval expressions that assume DOM elements exist when they don't (null deref); evaluating an expression that awaits a promise that rejects; CSP or page-context differences causing a function to be undefined; expressions referencing Node.js globals not present in the browser.

Related errors

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