Skip to content

fix(client): resolve hydration deadlock on HMR WebSocket failure#94086

Open
AryanXhauhan wants to merge 1 commit into
vercel:canaryfrom
AryanXhauhan:fix/turbopack-hydration-deadlock
Open

fix(client): resolve hydration deadlock on HMR WebSocket failure#94086
AryanXhauhan wants to merge 1 commit into
vercel:canaryfrom
AryanXhauhan:fix/turbopack-hydration-deadlock

Conversation

@AryanXhauhan
Copy link
Copy Markdown

Fix Turbopack Hydration Deadlock on HMR WebSocket Failure

Issue

React hydration hangs indefinitely in environments (like cross-origin WebViews) where the HMR WebSocket connection fails to open or is closed.

Root Cause

With Turbopack debug telemetry enabled, React enters dual-stream mode. If the HMR WebSocket connection fails to open or is terminated, the debug telemetry stream never receives its terminating chunk and remains pending indefinitely. This blocks the main server response from resolving and prevents hydration from executing.

Solution

  • Added lifecycle hook closeAllDebugChannels() in debug-channel.ts to safely close all active debug stream writers and clear the registry.
  • Added lifecycle hook resetDebugChannelState() to clear the initial document chunks buffer.
  • Wired these hooks directly into web-socket.ts:
    • resetDebugChannelState() is invoked inside init() prior to WebSocket creation.
    • closeAllDebugChannels() is invoked inside handleDisconnect() to immediately close unresolved debug streams on connection failure/disconnect.

This ensures graceful degradation. If the HMR WebSocket fails or drops, active debug streams are closed and the page hydrates successfully.

@AryanXhauhan AryanXhauhan marked this pull request as ready for review May 24, 2026 19:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant