Why Next.js freezes during hydration when using Full Stack Debug with Webpack

If your Next.js 14 or 15 app appears to hang, never finishes hydrating, or becomes unusable after starting Full Stack Debug, the issue is usually not your React code. It is typically caused by an interaction between the Webpack dev pipeline, the debugger attachment flow, and the browser waiting for client-side hydration assets that are delayed or paused.

The reproduction linked in this repository points to a debugging-specific freeze rather than a normal rendering bug. In practice, this shows up when running a debug profile that pauses the Node process or delays critical Webpack compilation steps long enough for the browser to stall during hydration.

Understanding the Root Cause

Hydration in Next.js depends on two things happening in sync:

1. The server must render HTML successfully.
2. The browser must download and execute the correct client JavaScript bundles so React can attach to that HTML.

When you launch Full Stack Debug, your editor often attaches debuggers to both the server and the browser. With Webpack-based development mode, this can introduce a timing problem:

• The Node inspector may pause the server on startup or on first statement.
• Webpack HMR and dev middleware may not finish emitting assets while the process is paused.
• The page HTML loads, but the browser waits for hydration scripts that are delayed, stale, or never fully served.
• React then appears to freeze because the app shell is visible, but client hydration never completes.

This is why the problem is often reproducible only in debug mode and disappears when you run the app normally.

There is another important detail in newer Next.js versions: Turbopack and Webpack behave differently under debug tooling. If you explicitly force Webpack in dev while using a launch configuration designed for a different runtime path, you can hit asset serving or source-map timing issues that look like hydration bugs but are really debugger-induced stalls.

In short, the root cause is usually one of these:

• The debug configuration pauses the server too early.
• The browser attaches before dev assets are ready.
• Webpack dev middleware is blocked by the debugger.
• Source map or HMR requests are delayed, preventing React from hydrating.

Step-by-Step Solution

The fix is to make sure the Next.js dev server starts cleanly, serves assets fully, and is only then attached to a debugger in a non-blocking way.

1. Do not pause on startup

Check your editor launch configuration and remove any option that pauses the Node process immediately, especially –inspect-brk. Use –inspect instead.

{
  "type": "node",
  "request": "launch",
  "name": "Next.js: server",
  "runtimeExecutable": "node",
  "runtimeArgs": ["--inspect"],
  "program": "node_modules/next/dist/bin/next",
  "args": ["dev"],
  "cwd": "${workspaceFolder}",
  "console": "integratedTerminal",
  "skipFiles": ["<node_internals>/**"]
}

If your current setup uses –inspect-brk, that is a common trigger for this issue.

2. Start the dev server first, then attach

Instead of launching server and browser in one aggressive debug sequence, start Next.js first and confirm it has compiled before opening the browser debugger.

npm run dev

Wait until you see the app compiled successfully, then attach your debugger separately.

{
  "type": "node",
  "request": "attach",
  "name": "Attach to Next server",
  "port": 9229,
  "restart": true,
  "skipFiles": ["<node_internals>/**"]
}

This prevents the initial asset pipeline from being blocked.

3. Prefer the official Next.js debug flow

If you are using VS Code, align your configuration with the documented Next.js approach rather than a generic full stack template. A safer pattern is:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "node",
      "runtimeArgs": ["--inspect"],
      "program": "node_modules/next/dist/bin/next",
      "args": ["dev"],
      "cwd": "${workspaceFolder}",
      "console": "integratedTerminal"
    },
    {
      "name": "Next.js: debug client",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    }
  ],
  "compounds": [
    {
      "name": "Next.js: debug full stack",
      "configurations": ["Next.js: debug server", "Next.js: debug client"]
    }
  ]
}

The key detail is that the server should not be launched in a mode that breaks before Webpack can serve hydration assets.

4. Test whether Webpack is the trigger

If your project can run with Turbopack, compare behavior between dev modes. This helps isolate whether the freeze is specifically tied to Webpack.

npx next dev

npx next dev --webpack

If the freeze only happens with –webpack under debug, that strongly confirms a tooling interaction rather than an app-level hydration mismatch.

5. Clear stale build artifacts

A partially built dev cache can make hydration symptoms worse after failed debug sessions.

rm -rf .next

npm run dev

On Windows PowerShell:

Remove-Item -Recurse -Force .next

npm run dev

6. Disable breakpoints that fire during bootstrap

Breakpoints in files executed during server initialization can block compilation and asset delivery. Temporarily disable breakpoints in:

• next.config.js or next.config.mjs
• custom server bootstrap files
• middleware or instrumentation files
• top-level module code imported by the app root

Then retest the debug flow.

7. Verify hydration is waiting on assets, not failing in React

Open browser DevTools and inspect the Network tab. If you see pending, delayed, or repeatedly retried requests for _next/static assets, the freeze is likely caused by dev asset delivery rather than a normal React hydration mismatch.

Also inspect the console. A true hydration mismatch usually logs React warnings. A debugger-related freeze often shows little or nothing beyond stalled network activity.

8. Use a simpler reproduction path for local debugging

If your goal is to debug app logic rather than the full Next.js startup lifecycle, use one of these safer workflows:

• Run the server normally and attach only when needed.
• Debug only the browser side first.
• Use server attach instead of server launch.

This avoids blocking the critical first compile that hydration depends on.

Common Edge Cases

Hydration mismatch vs hydration freeze

These are different problems. A hydration mismatch comes from inconsistent server/client rendering. A hydration freeze in this issue is more often caused by the debugger interrupting asset generation or delivery.

Custom Webpack configuration

If your project modifies webpack(config) in next.config.js, a plugin that slows compilation or changes source map behavior can make the debug freeze worse. Temporarily remove customizations to confirm.

Middleware and instrumentation

Code in middleware, instrumentation, or startup hooks may execute very early. If a breakpoint hits there, the app can look frozen before the browser gets everything needed for hydration.

Browser extension interference

Extensions that inject scripts into development pages can complicate hydration debugging. Test in an incognito window or a clean browser profile.

Different behavior between Next.js versions

Next.js 14 and 15 have differences in dev tooling internals. If one version freezes and another does not, compare:

• the exact debug configuration
• whether Webpack is forced
• whether source maps or experimental flags changed

Antivirus or filesystem watchers

On some machines, slow filesystem events can compound the pause introduced by debugging. This can make Webpack dev output appear stuck even when the real issue is timing-sensitive.

FAQ

Why does the page render HTML but never become interactive?

Because the server-side HTML was sent, but the client hydration bundle was delayed or blocked. React cannot attach event handlers until those scripts load and execute.

Why does this happen only in debug mode?

Debug mode can pause the Node.js process or alter startup timing. In a Webpack-based dev server, that pause may happen before critical client assets are compiled or served.

Should I switch away from Webpack to fix it?

Not necessarily. First fix the debug flow by avoiding startup pauses and using attach-based debugging. If the issue is still Webpack-specific, then comparing with Turbopack is useful for isolating the bug and deciding on a temporary workaround.

The practical resolution is simple: let Next.js finish booting, avoid break-on-start, and attach the debugger after the dev server is alive. That keeps the Webpack hydration pipeline unblocked and prevents the freeze seen in this issue.