Skip to content

stagehand-python@4.5.0a0.dev1730

@shrey150 shrey150 tagged this 20 Nov 22:55
<!-- CURSOR_AGENT_PR_BODY_BEGIN -->
# why

PostHog data (14 days to Nov 20 2026) shows ~18k browse CLI failures
landing as `unexpected` instead of typed codes:

| command | unexpected fails | installs |
|---------|-----------------|----------|
| `open` | 8,139 | 1,462 (3.1% of opens) |
| get/click/fill | 6,467 | 1,057 (~2%) |
| `wait` | 2,429 | 401 (mostly 30s timeouts) |
| screenshot | 1,207 | 247 |

Root cause: `daemon/server.ts` `formatError` only attached a `code` for
`DriverError` instances, so everything else came through as
`unexpected`.

# what changed

Add `packages/cli/src/lib/driver/error-classifier.ts` with
`classifyDriverError(error): DriverError | null` called in
`daemon/server.ts` `formatError` for non-DriverError errors. Also handle
`DriverError` in CLI catch block to report codes in telemetry for errors
thrown before the daemon starts.

Classified codes:
- `element_not_found` — "Could not find an element for the given
xPath(s): …"
- `wait_timeout` — waitForSelector timeout
- `navigation_timeout` — page.goto RPC timeout, navigation start timeout
- `page_unresponsive` — page.title/url/evaluate/screenshot RPC timeout,
enabling DOM timeout
- `invalid_url` — invalid navigation URL
- `browser_disconnected` — RPC client closed
- `cdp_unreachable` — CDP endpoint resolution failed
- `last_tab` — cannot close the last tab
- `session_mode_conflict` — session mode mismatch

Also rewrites the `element_not_found` message from the misleading
"xPath(s)" to:
> No element matches "selector". Run browse snapshot for fresh refs or
check the selector.

**before (main)**

```bash
$ browse click .nonexistent
Could not find an element for the given xPath(s): .nonexistent
# telemetry: result_code=unexpected

$ browse wait selector .loading --timeout 2000
waitForSelector timed out after 2000ms while waiting for selector
# telemetry: result_code=unexpected

$ browse tab close
Cannot close the last tab.
# telemetry: result_code=unexpected

$ browse open http://localhost:8000 --cdp 9998
Error: Unable to resolve CDP endpoint from port 9998. Is Chrome running with remote debugging?
# telemetry: result_code=unexpected
```

**after (this branch)**

```bash
$ browse click .nonexistent
No element matches ".nonexistent". Run browse snapshot for fresh refs or check the selector.
# telemetry: result_code=element_not_found

$ browse wait selector .loading --timeout 2000
waitForSelector timed out after 2000ms while waiting for selector
# telemetry: result_code=wait_timeout

$ browse tab close
Cannot close the last tab.
# telemetry: result_code=last_tab

$ browse open http://localhost:8000 --cdp 9998
DriverError: Unable to resolve CDP endpoint from port 9998. Is Chrome running with remote debugging?
Code: cdp_unreachable
# telemetry: result_code=cdp_unreachable
```

# test plan

- [x] `pnpm build --filter=browse` — TypeScript compiles
- [x] `pnpm vitest run tests/error-classifier.test.ts` — 17 test cases
covering all patterns
- [x] `pnpm vitest run tests/driver-errors.test.ts` — includes
formatError integration test
- [x] `pnpm vitest run` (all CLI tests) — 719 tests pass
- [x] Live testing against local Chrome (`--local --headless`) with
`BROWSERBASE_TELEMETRY_HOST` to a local listener
- [x] Formatting check passes
<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a
href="https://cursor.com/agents/bc-aef79a0e-41b4-5a0b-b9a9-a08daa6e8cef?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a
href="https://cursor.com/background-agent?bcId=bc-aef79a0e-41b4-5a0b-b9a9-a08daa6e8cef&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img
alt="Open in Cursor" width="131" height="28"
src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a>&nbsp;</div>

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Classifies common `browse` CLI failures with stable error codes so
telemetry stops reporting them as `unexpected`. Previously only
`DriverError` instances carried a code; now a new classifier maps known
error messages (element not found, wait/navigation timeouts,
unresponsive pages, invalid URLs, disconnected browsers, unreachable CDP
endpoints, closing the last tab) and rewrites the `element_not_found`
message to mention the selector instead of "xPath(s)".

- Adds `classifyDriverError` in `error-classifier.ts`, called from
`daemon/server.ts` `formatError` for non-`DriverError` errors.
- Reports typed codes in CLI telemetry by handling `DriverError` in
`base.ts`; matches `wait_timeout` against the actual "waitForSelector
timed out after" message format.
- Adds typed codes at throw sites: `cdp_unreachable`, `last_tab`, and
`session_mode_conflict`.
- `navigation_timeout` also covers `page.reload`, `page.go_back`, and
`page.go_forward` timeouts.
- Includes 19 classifier test cases plus formatError integration tests;
all 719 CLI tests pass.

<sup>Written for commit 28a39fdca3a4620da580e2a0f642593ab80cc658.
Summary will update on new commits.</sup>

<a
href="https://cubic.dev/pr/browserbase/stagehand/pull/3515?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="View guided diff"
src="https://www.cubic.dev/buttons/review-in-cubic-light.svg"></picture></a>
<a
href="https://www.cubic.dev/action/auto-fix/pr/browserbase/stagehand/3515?returnTo=https%3A%2F%2Fgithub.com%2Fbrowserbase%2Fstagehand%2Fpull%2F3515&source=description"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/turn-on-auto-fix-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/turn-on-auto-fix-light.svg"><img
alt="Turn on auto-fix"
src="https://www.cubic.dev/buttons/turn-on-auto-fix-light.svg"></picture></a>

<!-- End of auto-generated description by cubic. -->

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Assets 2
Loading