
Content creator and developer at UICraft Marketplace, sharing insights and tutorials on modern web development.
Save hours of development time with our premium Next.js templates. Built with Next.js 16, React 19, and Tailwind CSS 4.
Get the latest articles, tutorials, and product updates delivered to your inbox.
There's nothing more frustrating than setting up your VSCode debugger exactly as the official Next.js documentation describes, placing a breakpoint in your Server Component, hitting F5... and watching that breakpoint turn gray with the dreaded "Breakpoint set but not yet bound" message.
You're not alone. This issue has plagued developers across GitHub issue #62008 and issue #56702, affecting hundreds of developers trying to debug their Next.js applications. When your VSCode breakpoints not binding Next.js Server Components becomes your daily reality, productivity grinds to a halt.
This guide will walk you through understanding why this happens and, more importantly, how to fix it permanently.
The problem manifests itself in a predictable pattern. You create a fresh Next.js project using create-next-app, add the official debugging configuration from the Next.js debugging documentation, set a breakpoint in a Server Component, and start debugging.
Here's what happens:
The official launch.json configuration looks correct:
{
"version": "0.2.0",
"configurations": [
{
"name": "Next.js: debug server-side",
"type": "node-terminal",
"request": "launch",
"command": "npm run dev -- --inspect"
},
{
"name": "Next.js: debug full stack",
"type": "node",
"request": "launch",
"program": "${workspaceFolder}/node_modules/next/dist/bin/next",
"runtimeArgs": ["--inspect"],
"skipFiles": ["<node_internals>/**"],
"serverReadyAction": {
"action":
Yet breakpoints in files like app/page.tsx or app/api/route.ts refuse to bind. The debug session runs, your application works, but stepping through server-side code becomes impossible.
This is particularly problematic for intermediate developers who are:
The root cause isn't a bug in VSCode or an incorrect configuration on your part. It's a source map path mismatch between how Next.js (via Turbopack or Webpack) generates source maps and how VSCode expects to find your original source files.
Source maps create a mapping between your compiled/bundled JavaScript code and your original TypeScript/JSX source files. When you set a breakpoint in app/page.tsx, VSCode needs to know which line in the compiled bundle corresponds to that location.
Next.js compiles your code and generates source maps with specific path prefixes:
/turbopack/[project]/src/app/page.tsxwebpack://_N_E/./src/app/page.tsxVSCode receives these source map paths and tries to map them back to your workspace files. Here's where the problem occurs:
/turbopack/[project]/src/app/page.tsx/Users/you/myproject/turbopack/[project]/src/app/page.tsx/Users/you/myproject/src/app/page.tsxThe debugger can't find your files because the paths don't match. This regression in VSCode breakpoints not binding Next.js Server Components appeared after changes to how both Turbopack and Webpack generate source map paths in newer Next.js versions.
Client-side debugging often works because the Chrome DevTools extension handles path resolution differently, and the browser's debugger has its own source map processing that's more forgiving of path variations. The Node.js debugger used for Server Components is stricter about path matching.
This problem intensified with:
Different Next.js versions may use different source map path formats, which explains why some developers experience this issue while their colleagues don't—they might be on slightly different versions or using different bundler configurations.
The solution is to add sourceMapPathOverrides to your launch.json configuration. This tells VSCode exactly how to translate the source map paths back to your actual file locations.
If you're using Turbopack (the default bundler in development mode for Next.js 15+), add this configuration:
{
"version": "0.2.0",
"configurations": [
{
"name": "Next.js: debug server-side (Turbopack)",
"type": "node-terminal",
"request": "launch",
"command": "npm run dev -- --inspect",
"sourceMapPathOverrides": {
"/turbopack/[project]/*": "${workspaceFolder}/*",
"/turbopack/[project]/./src/*": "${workspaceFolder}/src/*",
"/ROOT/*": "${workspaceFolder}/*"
}
},
{
"name": "Next.js: debug full stack (Turbopack)",
"type": "node",
"request": "launch",
The key override patterns are:
/turbopack/[project]/* → Maps Turbopack's project root to your workspace/turbopack/[project]/./src/* → Handles the ./src prefix variation/ROOT/* → Catches alternative root path formatsIf you're using Webpack (either by choice or in older Next.js versions), use these overrides:
{
"version": "0.2.0",
"configurations": [
{
"name": "Next.js: debug server-side (Webpack)",
"type": "node-terminal",
"request": "launch",
"command": "npm run dev -- --inspect --no-turbopack",
"sourceMapPathOverrides": {
"webpack://_N_E/./*": "${workspaceFolder}/*",
"webpack://_N_E/./src/*": "${workspaceFolder}/src/*",
"webpack:///./*": "${workspaceFolder}/*",
"webpack:///./src/*": "${workspaceFolder}/src/*"
}
},
{
"name": "Next.js: debug full stack (Webpack)",
"type": "node"
Note the inclusion of --no-turbopack to explicitly use Webpack.
For maximum flexibility, here's a complete launch.json that works with both Turbopack and Webpack:
{
"version": "0.2.0",
"configurations": [
{
"name": "Next.js: debug server (Turbopack)",
"type": "node-terminal",
"request": "launch",
"command": "npm run dev -- --inspect",
"sourceMapPathOverrides": {
"/turbopack/[project]/*": "${workspaceFolder}/*",
"/turbopack/[project]/./src/*": "${workspaceFolder}/src/*",
"/ROOT/*": "${workspaceFolder}/*"
}
},
{
"name": "Next.js: debug server (Webpack)",
"type": "node-terminal",
"request": "launch",
After updating your launch.json:
.next folder to remove cached compilations: rm -rf .nextYour breakpoint should now show as a solid red circle instead of gray, and execution should pause when that line is hit.
If breakpoints still don't bind, enable source map logging in VSCode:
Look for messages like:
SourceMap: /turbopack/[project]/src/app/page.tsx -> ...
This shows you exactly what paths VSCode is trying to resolve, helping you craft the correct sourceMapPathOverrides.
Prevention is better than cure. Here's how to avoid VSCode breakpoints not binding Next.js issues in the future:
Create a team-wide debugging configuration that includes both Turbopack and Webpack overrides. Store this in your project repository so everyone uses the same setup.
When upgrading Next.js versions:
sourceMapPathOverrides if paths changeBefore debugging a new project or after major changes:
sourceMapPathOverrides match the bundler.next cache folderCommit your .vscode/launch.json to version control. This ensures:
While fixing VSCode debugging, you might also use:
chrome://inspect)These complement VSCode debugging and provide fallbacks when breakpoint issues occur.
Bookmark and watch these GitHub issues for updates:
The Next.js team actively works on improving source map generation. Future versions may include fixes that simplify or eliminate the need for sourceMapPathOverrides.
/turbopack/[project]/* paths while Webpack uses webpack://_N_E/./* patterns—your sourceMapPathOverrides must match your bundlersourceMapPathOverrides to your launch.json to explicitly map source map paths to your workspace files.next cache and restart both VSCode and dev server after configuration changes for fixes to take effect.vscode/launch.json to version control so your entire team benefits from working debug configurationslaunch.json now — Copy the appropriate configuration from this guide based on whether you use Turbopack or Webpackapp/page.tsx and verify it binds correctlychrome://inspect for Node.js debugging as an alternative approachDebugging is a fundamental part of software development. Don't let source map issues force you back to console.log statements. With the right sourceMapPathOverrides, VSCode becomes the powerful debugging tool it was meant to be for your Next.js Server Components.