VS Code breakpoints crashing Next.js with SIGILL usually means the debugger is attaching to the wrong Node.js process or an incompatible runtime is being launched.

When this happens, VS Code appears to start debugging normally, but as soon as execution hits a breakpoint, the session freezes, exits, or terminates with Error Code SIGILL. In a Next.js app, this is commonly caused by one of four things: a mismatched Node.js version, debugging the wrapper process instead of the actual server process, stale source maps, or native dependencies compiled for a different architecture.

Understanding the Root Cause

SIGILL stands for illegal instruction. At the operating system level, it means a process tried to execute machine instructions that the current CPU or runtime could not handle. In the context of debugging a Next.js frontend in VS Code, this does not always mean your JavaScript is wrong. More often, it indicates that the debugger triggered a crash in the underlying Node.js process.

Why that happens in practice:

• Unsupported or unstable Node version: Next.js can behave unpredictably when launched under a Node version outside the framework’s supported range.
• Debugger attached to the wrong process: Next.js often starts multiple processes during development. If VS Code binds to a bootstrap process instead of the active server process, breakpoints can behave incorrectly.
• Corrupted build cache or source maps: Old files in .next or mismatched transpiled output can confuse breakpoint mapping and destabilize the session.
• Architecture mismatch: Native modules installed on one CPU architecture and executed on another can trigger low-level crashes during startup or debug attach.
• Problematic launch configuration: An incorrect launch.json using the wrong runtime executable, cwd, or auto-attach mode can cause VS Code to debug the wrong target.

With Next.js, breakpoints are especially sensitive because the development server uses hot reload, multiple worker processes, and transformed source files. If the debugger configuration is slightly off, a low-level runtime failure can surface as SIGILL.

Step-by-Step Solution

The safest fix is to standardize your runtime, clear generated files, and debug the real Next.js server process with an explicit VS Code configuration.

1. Verify your Node.js version

First, check which version of Node is running in the terminal that launches VS Code debugging.

node -v

Compare that version with the supported version for your installed Next.js release. If needed, switch to a stable LTS version such as Node 18 or Node 20.

nvm install 20
nvm use 20

If you use Windows and do not use nvm, reinstall Node.js from the official release page and make sure VS Code is restarted afterward.

2. Remove cached build output and reinstall dependencies

Delete the generated Next.js cache and reinstall packages so stale native artifacts and source maps do not interfere with debugging.

rm -rf .next node_modules package-lock.json
npm install

If you use Yarn or pnpm, use the matching lockfile and install command instead.

rm -rf .next node_modules yarn.lock
yarn install

rm -rf .next node_modules pnpm-lock.yaml
pnpm install

3. Start Next.js in a clean development session

Before attaching a debugger, make sure the app runs normally without breakpoints.

npm run dev

If the app crashes even without debugging, the issue is not the debugger itself. In that case, inspect dependency compatibility, native packages, or your Node installation first.

4. Use a reliable VS Code launch.json for Next.js

Create or update .vscode/launch.json with a configuration that launches Next.js directly through Node instead of relying on a generic browser-only setup.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev"
    },
    {
      "name": "Next.js: debug full stack",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "console": "integratedTerminal",
      "cwd": "${workspaceFolder}",
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

For many projects, node-terminal is more stable because it behaves closer to running the app manually in a shell.

5. Add a browser attach configuration if you need frontend breakpoints

If your breakpoints are in client-side React code rather than server-side Next.js code, launch the dev server separately and attach Chrome debugging instead.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch Chrome against localhost",
      "type": "pwa-chrome",
      "request": "launch",
      "url": "http://localhost:3000",
      "webRoot": "${workspaceFolder}"
    }
  ]
}

This matters because server breakpoints and browser breakpoints are different debugging targets. Trying to use a Node debugger for browser-rendered code can create confusing failures.

6. Disable experimental or unstable runtime options

If your project uses custom Node flags, remove them temporarily from scripts in package.json.

{
  "scripts": {
    "dev": "next dev"
  }
}

Then restart debugging. Flags such as custom loaders, inspect options, or architecture-specific environment tweaks can trigger crashes under debugger attach.

7. Rebuild native dependencies for your current machine

If your project depends on packages with native binaries, rebuild them after switching Node versions or moving between Intel and Apple Silicon environments.

npm rebuild

Then test again:

npm run dev

8. Update VS Code and the JavaScript debugger

Older debugger integrations can mishandle modern Next.js process trees. Update:

• VS Code
• JavaScript Debugger extension if separately installed
• Next.js
• Node.js

After updating, fully close VS Code and reopen the workspace.

9. Use the official Next.js debugging pattern

If custom launch settings continue to fail, switch to the simpler pattern: run the app in one terminal and attach only where needed.

npm run dev

Then use a browser debugging configuration for UI code, or an attach configuration for server code.

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

If you want to use this, start Next.js with inspect enabled:

node --inspect node_modules/next/dist/bin/next dev

10. Confirm the fix

A working setup should behave like this:

• The app starts without crashing.
• VS Code attaches successfully.
• Breakpoints become solid, not hollow.
• Execution pauses at the expected file and line.
• No SIGILL appears when stepping through code.

Common Edge Cases

Apple Silicon vs Intel dependency mismatch

If dependencies were installed under Rosetta or copied from another machine, native modules may crash only during debug attach. Delete node_modules and reinstall natively on the current architecture.

Breakpoints placed in transpiled or generated files

Set breakpoints in your actual source files, not generated code under .next. Incorrect source mapping can make the debugger appear broken even when the runtime is healthy.

Monorepo working directory issues

In a monorepo, VS Code may launch the command from the repository root instead of the app folder. Set the correct cwd in launch.json.

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

Port conflicts

If another process already uses port 3000 or 9229, debugging can fail silently or attach to the wrong process. Check active ports before launching.

lsof -i :3000
lsof -i :9229

Custom Babel or SWC configuration

Projects with nonstandard transpilation settings may generate source maps that do not align with breakpoint locations. Temporarily revert custom compiler settings to isolate the issue.

Extension conflicts in VS Code

Some debugging or runtime extensions can interfere with the built-in JavaScript debugger. Disable nonessential extensions and test again in a fresh VS Code window.

FAQ

Why does SIGILL happen only when I hit a breakpoint?

Because the debugger changes execution flow. When VS Code pauses or instruments the runtime, it can expose an underlying incompatibility in Node.js, native binaries, or the debug target process that normal execution does not trigger.

Should I debug Next.js with Node or Chrome in VS Code?

Use Node debugging for server-side code such as API routes, server rendering logic, or backend handlers. Use Chrome debugging for client-side React components running in the browser. Mixing those targets often causes misplaced breakpoints or unstable sessions.

What is the fastest way to fix this if I need a working debugger immediately?

Use a stable LTS version of Node.js, delete .next and node_modules, reinstall dependencies, run npm run dev manually to confirm the app is healthy, then use a minimal node-terminal or pwa-chrome configuration in VS Code. That resolves most real-world SIGILL debugging failures in Next.js projects.

If the issue still persists, inspect the project linked in the issue for custom runtime flags, architecture-specific packages, and any recent Node or dependency upgrades. In most cases, the crash is environmental rather than a bug in your breakpoint logic.