Chrome extension connection reliability improved
The browser automation relay now detects stale connections early through heartbeat pings, typed error messages replace cryptic timeouts, and dropped connections get a 15-second window to reconnect before tearing down Playwright.
When the Chrome extension lost its connection to the CDP relay, developers were left with silent failures and opaque timeout errors. The relay would wait indefinitely without knowing why the connection died or whether recovery was possible.
The system now sends heartbeat pings every 5 seconds and expects a pong response within 15 seconds. If the browser stops responding, the connection is terminated immediately rather than waiting for a command to time out. When the extension disconnects, a typed error surfaces immediately—browser_closed, extension_disconnected, debugger_detached, network_error, or heartbeat_timeout—instead of a generic "WebSocket closed" message.
Most importantly, transient disconnections no longer kill the entire session. A 15-second grace window allows the extension to reconnect and resume where it left off. The relay preserves its tab cache and Playwright state, resynchronizes the tab list on reconnect, and continues without interruption.
The changes span the @n8n/mcp-browser package's CDP relay server and the @n8n/mcp-browser-extension, with error handling wired through to the connection layer so AI agents receive actionable messages when the browser dies mid-operation.
View Original GitHub DescriptionFact Check
Summary
Improve CDP relay reliability when connecting to the Chrome extension:
- Add WebSocket heartbeat (ping/pong) to detect stale connections early
- Introduce typed disconnect error classes (
ExtensionDisconnectedError,BrowserDisconnectedError,RelayTimeoutError) for actionable error messages - Detect and recover from stale relay state instead of silently timing out
- Improve reconnection logic in both the relay and browser extension
Related Linear tickets, Github issues, and Community forum posts
https://linear.app/n8n/issue/NODE-4768
Review / Merge checklist
- PR title and summary are descriptive. (conventions)
- Docs updated or follow-up ticket created.
- Tests included.
- PR Labeled with
Backport to Beta,Backport to Stable, orBackport to v1(if the PR is an urgent fix that needs to be backported)