How to Fix: Cannot debug Next15 using turbopack on windows

Next.js 15 debugging with Turbopack on Windows fails because the debugger configuration often launches the dev server through a shell wrapper that changes how the Node inspector process is created. The result is simple but frustrating: the app starts, Turbopack runs, yet breakpoints stay unbound or the debugger never attaches to the actual Next.js server process.

Understanding the Root Cause

This issue happens because Next.js 15 + Turbopack uses a different startup path than the classic webpack dev server, and on Windows the default VS Code launch flow may invoke npm, cmd, or a shell shim instead of attaching directly to the real Node.js process that owns the inspector port.

There are three technical reasons behind the bug:

1. Shell indirection on Windows: when a debug profile launches npm run dev -- --turbo, VS Code may attach to the shell or package runner first, not the final Next.js runtime process.
2. Turbopack process behavior: with Turbopack, the underlying process tree differs from older Next.js startup behavior, so auto-attach is less reliable.
3. Incorrect executable targeting: if the debugger targets npm instead of the local next CLI through Node, source maps and inspector attachment can fail or attach too late.

In practice, this means the fix is usually to launch Next.js directly with Node, pass the –inspect flag explicitly, and avoid relying on a Windows shell entry point.

Step-by-Step Solution

The most reliable workaround is to replace the default turbo debug configuration with a direct Node launch configuration in VS Code.

1. Install dependencies

npm install

2. Create or update .vscode/launch.json

Use a configuration that starts the local Next.js binary through Node instead of through npm.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js 15 Turbopack (Windows fixed)",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "node",
      "runtimeArgs": [
        "--inspect",
        "${workspaceFolder}/node_modules/next/dist/bin/next",
        "dev",
        "--turbopack"
      ],
      "cwd": "${workspaceFolder}",
      "console": "integratedTerminal",
      "skipFiles": [
        "<node_internals>/**"
      ],
      "serverReadyAction": {
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "action": "debugWithChrome"
      }
    }
  ]
}

This configuration works better because it removes the extra Windows shell layer and starts the exact script that runs Next.js.

3. If breakpoints still do not bind, use a fixed inspect port

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js 15 Turbopack Inspect 9229",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "node",
      "runtimeArgs": [
        "--inspect=9229",
        "${workspaceFolder}/node_modules/next/dist/bin/next",
        "dev",
        "--turbopack"
      ],
      "cwd": "${workspaceFolder}",
      "console": "integratedTerminal",
      "skipFiles": [
        "<node_internals>/**"
      ]
    }
  ]
}

A fixed port helps when auto-assigned inspector ports conflict with other running Node processes.

4. Alternative: split server and browser debugging

If you want predictable debugging for both server code and client rendering, create one config for the server and a second one for the browser.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next Server (Turbopack)",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "node",
      "runtimeArgs": [
        "--inspect=9229",
        "${workspaceFolder}/node_modules/next/dist/bin/next",
        "dev",
        "--turbopack"
      ],
      "cwd": "${workspaceFolder}",
      "console": "integratedTerminal"
    },
    {
      "name": "Attach Chrome to Next",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000",
      "webRoot": "${workspaceFolder}"
    }
  ],
  "compounds": [
    {
      "name": "Full Stack Next Debug",
      "configurations": [
        "Next Server (Turbopack)",
        "Attach Chrome to Next"
      ]
    }
  ]
}

5. Remove conflicting debug settings

If you already have a generated Next.js debug profile, it may still point to npm run dev or a shell command. Replace it with the direct Node config above.

// Less reliable on Windows for this issue
{
  "name": "turbo",
  "type": "node-terminal",
  "request": "launch",
  "command": "npm run dev -- --turbo"
}

That style of config is exactly what commonly triggers the problem on Windows.

6. Start debugging

1. Open the Run and Debug panel in VS Code.
2. Select Next.js 15 Turbopack (Windows fixed).
3. Start the debugger.
4. Set a breakpoint in server-side code such as a route handler, server component boundary, or API logic.

If everything is configured correctly, the debugger should attach to the real Next.js Node process, and breakpoints should resolve normally.

7. Optional package script cleanup

You can keep your regular script simple:

{
  "scripts": {
    "dev": "next dev",
    "dev:turbo": "next dev --turbopack"
  }
}

Then continue using the direct VS Code debug configuration instead of launching through npm.

Common Edge Cases

Breakpoints are hollow or marked unverified

This usually means VS Code attached to the wrong process or the file path does not match the compiled source mapping. Launching next/dist/bin/next directly fixes most of these cases.

Port 9229 is already in use

Another Node process may still be running in the background. Kill existing processes or change the inspect port:

node --inspect=9230 node_modules/next/dist/bin/next dev --turbopack

The browser opens, but server breakpoints never hit

This is a classic sign that only the browser debugger attached. Make sure you are using a node launch config for the server, not only a Chrome launch config.

Using PowerShell, Git Bash, or another terminal profile

Different shells can change startup behavior on Windows. Directly invoking the Node executable avoids shell-specific wrapper issues.

Source maps work in webpack but not Turbopack

That does not necessarily mean your source files are wrong. It usually points to a debugger attachment problem rather than an application code problem.

Monorepo workspace path issues

If the app is inside a subfolder, update cwd and the path to next/dist/bin/next so VS Code launches the correct project root.

"cwd": "${workspaceFolder}/apps/web"

FAQ

Why does debugging work without Turbopack but fail with Turbopack on Windows?

Turbopack changes the startup/runtime flow enough that shell-based debug profiles on Windows become unreliable. Direct Node launching is more stable because the debugger attaches to the correct process immediately.

Can I keep using npm run dev -- --turbo?

Yes for normal development, but for debugging this specific issue, it is safer to bypass npm in launch.json and run the local Next.js CLI through Node.

Is this a Next.js bug or a VS Code bug?

It is best understood as a process-launch compatibility issue involving Next.js 15, Turbopack, Windows process spawning, and how VS Code attaches debuggers. The workaround is on the debugger configuration side.

If you want the most reliable fix for the repository linked in the issue, update the VS Code debug profile to launch Node directly against the local Next.js binary with –inspect. That removes the Windows shell indirection causing the debugger to miss the actual Turbopack server process.