#18907: Fix: Improve browser error messages to avoid misleading agents
size: XS
Cluster:
Error Handling Improvements
## Problem
The previous error handling in `enhanceBrowserFetchError` wrapped ALL browser errors with \"Can't reach the OpenClaw browser control service\", even for application errors like:
- \"Element 'e42' not found or not visible\"
- \"tab not found\"
- \"Unknown ref 'e131'\"
This made agents think the browser control service was down when it was actually just stale page elements or normal browser errors.
## Impact
Agents would:
- Stop using the browser tool entirely
- Report service outages when none existed
- Miss the actual error (stale elements) that could be fixed with a fresh snapshot
## Solution
Improved error handling that:
1. **Transforms abort errors** → clear timeout messages (`Request timed out after Xms`)
2. **Adds sandbox hints** only for actual connection failures to remote URLs
3. **Passes through application errors unchanged** (element/tab not found, etc.)
## Testing
- ✅ All browser client tests pass (6/6)
- ✅ Timeout detection test passes (abort → "timed out")
- ✅ Sandbox connection hint test passes
- ✅ Application errors no longer wrapped with misleading service messages
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
This PR significantly improves error handling in the browser client by addressing a critical issue where all browser errors were misleadingly wrapped with "Can't reach the OpenClaw browser control service", even for application-level errors like element/tab not found.
**Key improvements:**
- Transforms abort errors into clear timeout messages (`Request timed out after Xms`)
- Only adds sandbox connection hints for actual connection failures (ECONNREFUSED, etc.) to HTTP URLs
- Passes through application errors unchanged, allowing agents to see the real error and take appropriate action (e.g., refresh snapshot for stale elements)
**Impact:**
Previously, agents would misinterpret application errors as service outages and stop using the browser tool entirely. With this fix, agents can distinguish between actual service issues and recoverable errors like stale page elements.
**Testing:**
All browser client tests pass (6/6), including new tests for timeout detection and sandbox hint behavior. The logic correctly handles three error categories: timeouts, connection failures, and application errors.
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with minimal risk - it improves error handling without changing core functionality
- The change is well-contained to error handling logic, has comprehensive test coverage (6/6 tests passing including new tests for the specific scenarios), follows a clear improvement pattern (from wrapping all errors to selectively handling them), and the logic is straightforward with clear conditionals. The only minor issue is a slightly misleading comment that doesn't affect functionality.
- No files require special attention - the single file change is straightforward and well-tested
<sub>Last reviewed commit: 8ef182c</sub>
<!-- greptile_other_comments_section -->
<sub>(3/5) Reply to the agent's comments like "Can you suggest a fix for this @greptileai?" or ask follow-up questions!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#23668: fix: distinguish browser validation errors from connectivity failures
by davidemanuelDEV · 2026-02-22
84.2%
#14784: fix(browser): clarify stale targetId errors (tab not found)
by sovushik · 2026-02-12
81.0%
#9173: Fix: Improve error messaging for API rate limits and billing errors
by vishaltandale00 · 2026-02-04
80.1%
#14944: fix(browser): prefer openclaw profile in headless/noSandbox environ...
by BenediktSchackenberg · 2026-02-12
78.2%
#19451: fix(errors): surface provider hint for role-ordering failures
by rafaelipuente · 2026-02-17
78.1%
#10367: CLI/Ops: resilient browser fill + failover hardening + operations t...
by cluster2600 · 2026-02-06
77.4%
#9248: Fix: Webchat UI goes grey/unresponsive after Slack message tool calls
by vishaltandale00 · 2026-02-05
76.2%
#13960: fix(ui): preserve structured config validation error details
by constansino · 2026-02-11
76.2%
#4036: fix: include cause detail in agent connection error diagnostic
by anajuliabit · 2026-01-29
75.9%
#15050: fix: transcript corruption resilience — strip aborted tool_use bloc...
by yashchitneni · 2026-02-12
75.9%