#15595: fix(browser): avoid local port conflicts for remote cdp
stale
size: XS
Cluster:
Browser Enhancements and Fixes
## Summary
- avoid applying local CDP port-ownership conflict checks to remote CDP profiles
- return the correct remote websocket reachability error when remote CDP HTTP is reachable but websocket handshake fails
- add regression coverage for this branch in `server-context.remote-tab-ops.test.ts`
## Why
For remote CDP profiles (e.g. Browserless), OpenClaw can currently throw:
`Port <port> is in use for profile ... but not by openclaw`
This is a local profile ownership error and is misleading for remote endpoints. It blocks valid remote setups before the real websocket reachability error is surfaced.
## Changes
- `src/browser/server-context.ts`
- handle `remoteCdp` websocket failure before local ownership conflict checks
- preserve attach-target retry behavior for remote profiles
- keep existing local attachOnly/local restart paths unchanged
- `src/browser/server-context.remote-tab-ops.test.ts`
- add regression test asserting remote websocket failures no longer produce local port-in-use ownership errors
Fixes #15582
## Validation
- `pnpm check`
- `pnpm build`
- `pnpm vitest run src/browser/server-context.remote-tab-ops.test.ts`
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR adjusts `ensureBrowserAvailable()` in `src/browser/server-context.ts` so that remote CDP profiles (non-loopback CDP URLs) surface a remote WebSocket reachability error before running local port-ownership/"port in use" checks. It also preserves the existing attach-target retry callback for remote profiles.
A regression test was added in `src/browser/server-context.remote-tab-ops.test.ts` to assert that when remote CDP HTTP is reachable but the CDP WebSocket handshake fails, the thrown error message is the remote-websocket error (and does not mention the local "Port <port> is in use" ownership conflict).
Overall, the change is localized to remote CDP error ordering and does not alter local profile restart/attachOnly behavior beyond removing the remote-CDP special-casing from the local attachOnly branch (remote now always reports the remote-websocket error).
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with minimal risk.
- Changes are small and localized to error-path ordering in `ensureBrowserAvailable()` for remote CDP profiles, and the added test covers the previously misleading error message. No API surface changes or broad refactors were introduced.
- No files require special attention
<sub>Last reviewed commit: b7b9e77</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#9020: fix(browser): skip port ownership and WS reachability checks for re...
by yepack · 2026-02-04
86.6%
#13568: Fix browser (OpenClaw-managed) launch fail by binding remote debugg...
by singlag · 2026-02-10
81.1%
#22952: fix(browser): suggest remote profile when local Chrome is not insta...
by dashed · 2026-02-21
80.2%
#14944: fix(browser): prefer openclaw profile in headless/noSandbox environ...
by BenediktSchackenberg · 2026-02-12
79.4%
#16030: fix(browser): extend single-tab fallback to remote CDP profiles
by lailoo · 2026-02-14
77.5%
#17760: fix(browser): rewrite 0.0.0.0 and [::] wildcard addresses in CDP We...
by joeharouni · 2026-02-16
76.9%
#19495: fix: handle Chrome process re-parenting on Windows
by andenwick · 2026-02-17
76.2%
#14784: fix(browser): clarify stale targetId errors (tab not found)
by sovushik · 2026-02-12
76.0%
#10367: CLI/Ops: resilient browser fill + failover hardening + operations t...
by cluster2600 · 2026-02-06
75.6%
#8614: fix(browser): detect early chromium exit to prevent startup hang
by Wren-OC · 2026-02-04
75.2%