fix(tools): Add browser crash detection and automatic session recovery by VascoSch92 · Pull Request #2738 · OpenHands/software-agent-sdk

VascoSch92 · 2026-04-07T10:15:35Z

Summary

Adds crash detection to BrowserToolExecutor: after 3 consecutive action failures, the browser session is automatically reset (_initialized = False) so the next action re-creates it
Uses a shorter timeout (30s instead of 300s) after a failure to avoid long cascading waits against a dead browser
Resets the failure counter on success
Includes recovery context in error messages so the agent knows the browser was restarted

Previously, when the browser crashed, every subsequent action would block for 300 seconds before timing out, effectively making the agent "stuck". Now the executor detects the pattern and recovers automatically.

Fixes #2412

Test plan

3 new tests: test_issue_2412_consecutive_failures_reset_session, test_issue_2412_success_resets_failure_counter, test_issue_2412_degraded_timeout_after_failure
All 59 existing browser unit tests pass
Manual test: start a browser task, kill chrome, verify agent recovers

Agent Server images for this PR

• GHCR package: https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server

Variants & Base Images

Variant	Architectures	Base Image	Docs / Tags
java	amd64, arm64	`eclipse-temurin:17-jdk`	Link
python	amd64, arm64	`nikolaik/python-nodejs:python3.13-nodejs22-slim`	Link
golang	amd64, arm64	`golang:1.21-bookworm`	Link

Pull (multi-arch manifest)

# Each variant is a multi-arch manifest supporting both amd64 and arm64
docker pull ghcr.io/openhands/agent-server:0f1b740-python

Run

docker run -it --rm \
  -p 8000:8000 \
  --name agent-server-0f1b740-python \
  ghcr.io/openhands/agent-server:0f1b740-python

All tags pushed for this build

ghcr.io/openhands/agent-server:0f1b740-golang-amd64
ghcr.io/openhands/agent-server:0f1b740-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:0f1b740-golang-arm64
ghcr.io/openhands/agent-server:0f1b740-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:0f1b740-java-amd64
ghcr.io/openhands/agent-server:0f1b740-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:0f1b740-java-arm64
ghcr.io/openhands/agent-server:0f1b740-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:0f1b740-python-amd64
ghcr.io/openhands/agent-server:0f1b740-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-slim-amd64
ghcr.io/openhands/agent-server:0f1b740-python-arm64
ghcr.io/openhands/agent-server:0f1b740-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-slim-arm64
ghcr.io/openhands/agent-server:0f1b740-golang
ghcr.io/openhands/agent-server:0f1b740-java
ghcr.io/openhands/agent-server:0f1b740-python

About Multi-Architecture Support

Each variant tag (e.g., 0f1b740-python) is a multi-arch manifest supporting both amd64 and arm64
Docker automatically pulls the correct architecture for your platform
Individual architecture tags (e.g., 0f1b740-python-amd64) are also available if needed

When the browser crashes, BrowserToolExecutor now detects consecutive failures and automatically resets the session instead of looping on the dead connection with 300-second timeouts. Changes: - Track consecutive action failures in BrowserToolExecutor - After 3 consecutive failures, set _initialized=False to trigger session re-creation on the next action - Use a shorter timeout (30s) after a failure to avoid long waits against a potentially dead browser - Reset failure counter on success - Include recovery context in error messages so the agent knows the browser was restarted Fixes #2412 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

github-actions · 2026-04-07T10:16:03Z

Python API breakage checks — ✅ PASSED

Result: ✅ PASSED

Action log

github-actions · 2026-04-07T10:16:12Z

REST API breakage checks (OpenAPI) — ✅ PASSED

Result: ✅ PASSED

Action log

all-hands-bot

Pragmatic solution to a real problem. The recovery logic is straightforward and well-tested. However, this changes tool execution behavior (timeouts and automatic recovery), which per repo guidelines requires eval verification before approval. Please run lightweight evals to ensure no unexpected benchmark impact.

github-actions · 2026-04-07T10:22:40Z

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-tools/openhands/tools/browser_use
impl.py	278	173	37%	57–61, 63–64, 66, 68, 70–73, 75–76, 78, 80, 87, 105–108, 114–115, 120, 122–124, 126–127, 135–137, 139–143, 148, 199, 204–207, 209, 231–233, 236–238, 240, 253, 290–291, 295, 305, 320–321, 326, 343, 349–350, 355, 360, 366–367, 371–372, 378–379, 387–390, 395–397, 404, 412, 430–431, 433–446, 449–462, 464–465, 471, 476–479, 487, 489, 492–493, 499–500, 505–506, 512–513, 517–518, 522–523, 527, 529–530, 532–535, 538–539, 545, 547, 549, 557–558, 562–563, 568–569, 573–574, 578–579, 584–585, 597–598, 609–610, 614–618, 632–634, 639, 644–645, 655, 661–662
TOTAL	24047	12270	48%

…mport Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Attempt to cleanup the old browser process/session before setting _initialized=False. Uses a short 5s timeout since the browser may be crashed or wedged. Failures are caught and logged at debug level since they're expected when the browser is truly dead. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

all-hands-bot

Taste Rating: 🟡 Acceptable - Pragmatic solution to a real problem, but the design conflates browser crashes with legitimate action errors.

Verdict: ❌ Needs eval verification - Per the previous review and repo guidelines, changes to tool execution behavior (timeouts, automatic recovery) require lightweight eval runs before approval. Please run evals to verify no unexpected benchmark impact.

Regular action errors (invalid selector, missing element) are normal agent mistakes, not browser crashes. Only timeouts indicate a potentially dead/hung browser and should count toward session reset. Also makes degraded timeout less aggressive: kicks in after 2+ consecutive timeouts instead of after any single failure. Adds test for action errors not triggering reset. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

all-hands-bot

Pragmatic solution to a real problem. The recovery logic is straightforward and well-tested. However, this changes tool execution behavior (timeouts and automatic recovery), which per repo guidelines requires eval verification before approval. Please run lightweight evals to ensure no unexpected benchmark impact.

VascoSch92 · 2026-04-07T12:16:28Z

@OpenHands fix the pre-commit check

openhands-ai · 2026-04-07T12:16:49Z

I'm on it! VascoSch92 can track my progress at all-hands.dev

Co-authored-by: openhands <openhands@all-hands.dev>

openhands-ai · 2026-04-07T12:18:30Z

Summary

I fixed the pre-commit check failure on PR #2738.

What was done:

Root cause: The ruff-format pre-commit hook was failing because of a formatting issue in tests/tools/browser_use/test_browser_executor.py

Fix applied: Changed a 3-line function call to a single line (line 333) as required by ruff-format:

# Before
error_result = BrowserObservation.from_text(
    text="Element not found", is_error=True
)

# After
error_result = BrowserObservation.from_text(text="Element not found", is_error=True)

Committed and pushed: Commit bf0ed5dd with the fix

Checklist:

Pre-commit check fixed (verified locally with uv run pre-commit run --files)
Changes are minimal and targeted (only 1 file changed, 1 insertion, 3 deletions)
Commit includes required co-author line
Pushed to fix/browser-crash-recovery branch to update PR fix(tools): Add browser crash detection and automatic session recovery #2738

xingyaoww · 2026-04-21T13:59:20Z

@OpenHands /codereview /github-pr-review

🤖 This comment was automatically posted by the pr-triage skill (OpenHands) on behalf of a maintainer. See PR #2906 for skill details.

openhands-ai · 2026-04-21T13:59:36Z

I'm on it! xingyaoww can track my progress at all-hands.dev

xingyaoww

🟡 Acceptable — Solid, pragmatic fix for a real user-facing problem. The approach is clean: count consecutive timeouts, degrade the timeout to avoid long cascading waits, reset the session after enough evidence of a dead browser. Tests cover the important cases well.

⚠️ Eval risk: This changes browser tool execution behavior (crash recovery, timeout degradation), which could plausibly affect benchmark performance. Flagging for a human maintainer to validate after running lightweight evals.

[RISK ASSESSMENT]

[Overall PR] ⚠️ Risk Assessment: 🟡 MEDIUM
The crash recovery mechanism changes how the agent experiences browser failures — instead of indefinite 300s timeouts, it now gets faster failure signals and automatic session restarts. This is almost certainly a net positive for agent reliability, but the changed timing/error messages could affect agent decision-making in benchmarks.

VERDICT:
✅ Worth merging pending eval validation.

KEY INSIGHT:
The core mechanism (timeout counter → degraded timeout → session reset) is simple and correct; the main improvement opportunity is eliminating the magic number coupling between the degraded-timeout threshold and MAX_CONSECUTIVE_FAILURES.

This review was generated by an AI assistant (OpenHands) on behalf of xingyaoww.

openhands-ai · 2026-04-21T14:02:20Z

Summary

I completed the requested code review of PR #2738 ("fix(tools): Add browser crash detection and automatic session recovery") and posted it as a GitHub PR review.

What was done:

✅ Retrieved and analyzed the full PR diff — Examined changes to impl.py (crash detection logic) and test_browser_executor.py / test_browser_initialization.py (new and updated tests).
✅ Posted a structured code review using the /codereview and /github-pr-review skill guidelines, including:
- Overall taste rating (🟡 Acceptable)
- Risk assessment (🟡 MEDIUM)
- Two inline comments with GitHub suggestion syntax:
  - 🟠 Important: Magic number 2 should be MAX_CONSECUTIVE_FAILURES - 1 to make the coupling explicit
  - 🟡 Suggestion: Missing return type annotation on _handle_timeout_failure
- Verdict (✅ Worth merging pending eval validation)
✅ Followed eval-risk policy — Since the PR changes browser tool execution behavior (timeouts, error messages, crash recovery), I used COMMENT instead of APPROVE per the repo's custom codereview guide, flagging it for human maintainer validation after lightweight evals.
✅ No code changes were made — This was a review-only task, as instructed by the codereview skill ("DO NOT modify the code; only provide specific, actionable feedback").
✅ AI disclosure included in the review body.

Review posted at: #2738 (review)

github-actions · 2026-04-23T09:42:47Z

📁 PR Artifacts Notice

This PR contains a .pr/ directory with PR-specific documents. This directory will be automatically removed when the PR is approved.

For fork PRs: Manual removal is required before merging.

VascoSch92 · 2026-04-23T09:43:03Z

I run an eval of Gaia (only benchmark which is using the Browser tool): https://openhands-eval-monitor.vercel.app/?run=gaia%2Flitellm_proxy-claude-sonnet-4-5-20250929%2F24825062866%2F&days=15

And we have:

No regression attributable to PR fix(tools): Add browser crash detection and automatic session recovery #2738. Browser tool was invoked heavily, succeeded every time, no crashes, zero retries, zero infra escalation. The new crash-recovery code is inert in this run.
But this is not positive evidence either. The PR's value only materializes when the browser actually crashes — and none did here. To validate the fix, you'd want a run where the old code would hang for 300 s on a dead browser and see the new code recover. If you have a reproducer (maybe the original [Bug]: Agent fails to recover from browser crash during long-running tasks #2412 issue has one), trigger an eval with it to show the recovery branch firing.

So I pushed a testing script in .pr which should trigger the new code.

all-hands-bot · 2026-04-26T12:28:32Z

[Automatic Post]: This PR seems to be currently waiting for review. @xingyaoww, could you please take a look when you have a chance?

all-hands-bot · 2026-05-03T12:31:41Z

[Automatic Post]: It has been a while since there was any activity on this PR. @VascoSch92, are you still working on it? If so, please go ahead, if not then please request review, close it, or request that someone else follow up.

all-hands-bot · 2026-05-07T12:54:12Z

[Automatic Post]: This PR seems to be currently waiting for review. @xingyaoww, could you please take a look when you have a chance?

OpenHands#2738) Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: openhands <openhands@all-hands.dev>

VascoSch92 requested a review from all-hands-bot April 7, 2026 10:18

all-hands-bot reviewed Apr 7, 2026

View reviewed changes

Comment thread openhands-tools/openhands/tools/browser_use/impl.py Outdated

Comment thread openhands-tools/openhands/tools/browser_use/impl.py

VascoSch92 changed the title ~~Add browser crash detection and automatic session recovery~~ fix(tools): Add browser crash detection and automatic session recovery Apr 7, 2026

VascoSch92 and others added 3 commits April 7, 2026 12:24

Use typing.Final for module-level constants, remove redundant local i…

56babdd

…mport Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Fix ruff line length violation

35953d2

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

VascoSch92 requested a review from all-hands-bot April 7, 2026 10:36

all-hands-bot reviewed Apr 7, 2026

View reviewed changes

Comment thread openhands-tools/openhands/tools/browser_use/impl.py Outdated

Comment thread openhands-tools/openhands/tools/browser_use/impl.py

Comment thread openhands-tools/openhands/tools/browser_use/impl.py

Comment thread tests/tools/browser_use/test_browser_executor.py

VascoSch92 requested a review from all-hands-bot April 7, 2026 10:49

all-hands-bot reviewed Apr 7, 2026

View reviewed changes

fix(tests): Apply ruff-format to test file

bf0ed5d

Co-authored-by: openhands <openhands@all-hands.dev>

This comment was marked as off-topic.

Sign in to view

xingyaoww reviewed Apr 21, 2026

View reviewed changes

Comment thread openhands-tools/openhands/tools/browser_use/impl.py

Comment thread openhands-tools/openhands/tools/browser_use/impl.py Outdated

VascoSch92 and others added 3 commits April 23, 2026 09:33

address feedbacks

d7d33ea

Merge branch 'main' into fix/browser-crash-recovery

7f70cd5

testing script

fef5719

VascoSch92 requested a review from xingyaoww April 23, 2026 09:43

Merge branch 'main' into fix/browser-crash-recovery

2581cb7

neubig approved these changes May 8, 2026

View reviewed changes

Merge branch 'main' into fix/browser-crash-recovery

0f1b740

neubig enabled auto-merge (squash) May 8, 2026 17:37

neubig merged commit 4b7867d into main May 8, 2026
24 of 26 checks passed

neubig deleted the fix/browser-crash-recovery branch May 8, 2026 17:44

Conversation

VascoSch92 commented Apr 7, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

github-actions Bot commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Python API breakage checks — ✅ PASSED

Uh oh!

github-actions Bot commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

REST API breakage checks (OpenAPI) — ✅ PASSED

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

VascoSch92 commented Apr 7, 2026

Uh oh!

openhands-ai Bot commented Apr 7, 2026

Uh oh!

openhands-ai Bot commented Apr 7, 2026

Summary

What was done:

Checklist:

Uh oh!

This comment was marked as off-topic.

This comment was marked as off-topic.

xingyaoww commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openhands-ai Bot commented Apr 21, 2026

Uh oh!

xingyaoww left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

openhands-ai Bot commented Apr 21, 2026

Summary

What was done:

Uh oh!

github-actions Bot commented Apr 23, 2026

Uh oh!

VascoSch92 commented Apr 23, 2026

Uh oh!

all-hands-bot commented Apr 26, 2026

Uh oh!

all-hands-bot commented May 3, 2026

Uh oh!

all-hands-bot commented May 7, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

VascoSch92 commented Apr 7, 2026 •

edited by github-actions Bot

Loading

github-actions Bot commented Apr 7, 2026 •

edited

Loading

github-actions Bot commented Apr 7, 2026 •

edited

Loading

github-actions Bot commented Apr 7, 2026 •

edited

Loading

xingyaoww commented Apr 21, 2026 •

edited

Loading