AI & Agent Dev Bug Sandbox logo
AI & Agent Dev Bug Sandbox
Back to Radar

Turbopack HMR WebSocket Blocks Client Module Evaluation, Preventing Hydration In Cross-Origin WebView

Next.js 16.2.x with Turbopack regressed: when the HMR WebSocket fails to connect (e.g., in a cross-origin Android WebView), the module loader awaits the connection before executing client code, so React never hydrates. Server-rendered HTML appears but no interactivity, with no console errors.

highConfidence 90%Next.jsAffected V16.2.0Affected V16.2.6

Origin Analysis

In Next.js 16.2.0, the Turbopack runtime changed the module evaluation sequence to establish the HMR WebSocket connection before running client modules. When the WebSocket cannot connect (due to cross-origin policy or WebView restrictions), the connection promise never resolves, blocking all subsequent client code including React hydration. This was not the case in 16.0.10.
1. Create a Next.js App Router project with `output: 'export'` and `assetPrefix` pointing to a network IP (e.g., `http://192.168.1.7:3000`). 2. Run `next dev` with Turbopack (default in Next.js 16). 3. Load the app in a cross-origin Android WebView (e.g., Tauri v2 dev mode). 4. Observe that server HTML is visible, but `useEffect` never fires, onClick handlers are not attached, and no JavaScript errors appear.

Fixing Code Block

Edge Case Audit

Making HMR non-blocking means that hot module replacement will not work if the WebSocket connection fails. In a development environment where HMR is expected, users may miss live updates silently. Rollback is straightforward: restore the original `await startHMR()` line. Additionally, ensure that any HMR event handlers are attached after the socket opens to avoid race conditions with module execution.

Ecosystem Topology