next.js: Debugger not binding breakpoints in VSCode in server components, using official Next.js debugger setup

Link to the code that reproduces this issue

https://github.com/andrewmartin/nextjs-example

To Reproduce

  1. Open the code in VSCode
  2. Add a breakpoint in any server side files
  3. Open the “Run and Debug” panel
  4. Select “Next.js: debug full stack” and press “F5” or the play button
  5. Note that breakpoints don’t land when requests are made in either scenario.

Breakpoints set in server components that aren’t attached (sorry the screencaps below didn’t show my mouse hover so here’s a gif):

Zight Recording 2024-02-13 at 09 45 03 AM

page tsx — tmp2 2024-02-13 at 9 36 58 AM route ts — tmp2 2024-02-13 at 9 38 08 AM

Debug diagnostics:

Debug Diagnostics — tmp2 2024-02-13 at 9 39 02 AM

Some of the sources loaded (I can provide more if needed):

Debug Diagnostics — tmp2 2024-02-13 at 9 39 53 AM

Current vs. Expected behavior

Hi everyone! The code repo shared is a brand new, blank create-next-app using Typescript, Next 14, and the app directory. I only added the debugging setup from the official docs and a single basic API endpoint at /api/health and that’s it. For some reason I cannot for the life of me get my breakpoints to attach.

Well, that’s partially true, The only breakpoints that seem to be mapped with my codebase are those in the Browser / client side components. I have tried SO many things to get this to work and have read probably about 30 posts about trying to fix this.

I’d love to know if anyone has any ideas why a vanilla Next.js project might not find my sources. Thanks in advance for your help!

Provide environment information

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 23.3.0: Wed Dec 20 21:30:44 PST 2023; root:xnu-10002.81.5~7/RELEASE_ARM64_T6000
Binaries:
  Node: 20.11.0
  npm: 10.2.4
  Yarn: 1.22.21
  pnpm: N/A
Relevant Packages:
  next: 14.1.0
  eslint-config-next: 14.1.0
  react: 18.2.0
  react-dom: 18.2.0
  typescript: 5.3.3
Next.js Config:
  output: N/A

Which area(s) are affected? (Select all that apply)

Not sure

Which stage(s) are affected? (Select all that apply)

next dev (local)

Additional context

I have tried:

  • Using blank (vanilla) VSCode insiders
  • Using alternative node versions (node 18, other minor node 20)
  • Tried mucking around with the launch config a bit, like adjusting sourceMapPathOverrides etc

Some of my colleagues have had luck seeing them, others have not.

About this issue

  • Original URL
  • State: open
  • Created 3 years ago
  • Reactions: 42
  • Comments: 77 (2 by maintainers)

Most upvoted comments

Hi all,

I’ve just been down this rabbit hole and its terrible. By a stroke of luck, I could get it working. I might be repeating what is already said here, just from a different perspective which may help someone.

Full degression, running Next 14.1.4, Node v20.11.0 (LTS) (in WSL - probably irrelevant, so I’ll just say Ubuntu). I’ve tested it in pages and app router.

This is the first time I’ve actually been able to get a NodeJS application actually to debug, and I can’t believe it.

My environment is turborepo (soon to be nx, but thats another story).

I can confirm my relative path to next is apps/web from the root. and in the end, it didn’t matter anyway.

My symptoms were a lot the same as the others here, client side is perfect, server side might as well be located in Mars for all I knew. I looked in the NodeJS debug tool and saw that only a subset of my server files were actually being exposed.

image

After actually using my eyes 👀 I saw this.

> NODE_OPTIONS='--inspect' next dev

Debugger listening on ws://127.0.0.1:9229/99f15ee9-6b51-46b4-a070-ccc8bcb60e76
For help, see: https://nodejs.org/en/docs/inspector
Debugger listening on ws://127.0.0.1:9230/42518e76-ee66-44ea-9cb5-a575f1d5fd0c
For help, see: https://nodejs.org/en/docs/inspector
   the --inspect option was detected, the Next.js router server should be inspected at port 9230.

Now call me stupid or ADHD riddled, but I stopped looking normally at the first line mentioning port 9229. It sneaks in 9230 which i found the NodeJS debug tool via Chrome does NOT add by default. At this point I didn’t go straight to vscode. I stayed with the Node debugger to do some more testing. I added it in.

image

After adding it in and probably restarting the dev server with the documented normal command via Package JSON script

{
....
"scripts": {
"debug": "NODE_OPTIONS='--inspect' next dev",
}
...

I looked at the sources tab in Node Devtools

image

and it actually had web listed there which is the folder NextJS is in (as im running monorepo). My cardiovascular signs increased. I then added a breakpoint in the Chrome devtools using the file explorer in sources and clicking on a line number in the file previewer.

image

I ran the code, and the breakpoint tripped. I thought I was tripping instead to be honest, this is the closest I’ve ever gotten.

Only now did I go back to VSCode Debug

I made the new debug file which I’ve rage deleted many times.

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "attach",
            "name": "Attach to Node",
            "port": 9230,
            "skipFiles": [
                "<node_internals>/**"
            ],
            "cwd": "${workspaceFolder}/apps/web" // I have this because it lives in subfolders, if you're soloing it with no monorepo, you can remove this
        },
        // Below is irrelevant to this post but whatever
        {
            "name": "Next.js: debug client-side",
            "type": "chrome",
            "request": "launch",
            "url": "http://localhost:3000",
            "cwd": "${workspaceFolder}/apps/web",
        },
    ]
}

IMPORTANT SIDE NOTE: This does not start your dev server, it purely connects to what is running, so start your dev server with inspect as per previous Package JSON mention.

The debugger attached but breakpoints are still not red/are hollow with no fill. I tried it anyway, and it worked.

image

Things that did not work for me

  • Preserve symlinks message said to add the argument, I got worse errors so I removed it.
  • Adding a source maps override
  • Adding the outFiles pointing to the .next directory. While it technically did work, vscode would only show the webpack compiled version which is better than nothing, but is yucky none the less.

Things that may be useful troubleshooting

Everyone mentions ${workspaceFolder} in their configurations, but if you are unsure what it is, or you have doubts vscode is selecting the right one, use this echo task to double check it. It’s for Linux/WSL so adopt to Windows how you see fit. or ChatGPT it.

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "echo",
            "type": "shell",
            "command": "echo ${workspaceFolder}"
        }
    ]
}

I hope this helps you on your journey of accelerated hair loss.

I’ve been facing the same issue, and ultimately the discussion in #56702 is what helped me solve it.

Add the following launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev",
      "sourceMaps": true,
      "sourceMapPathOverrides": {
        "/turbopack/[project]/*": "${webRoot}/*"
      }
    },
    {
      "name": "Next.js: debug client-side",
      "type": "msedge",
      "request": "launch",
      "url": "http://localhost:3000",
      "webRoot": "${workspaceFolder}",
      "sourceMaps": true,
      "sourceMapPathOverrides": {
        "/turbopack/[project]/*": "${webRoot}/*"
      }
    }
  ]
}

If you’re not using Turbopack, replace sourceMapPathOverrides with: (haven’t tried this one)

"sourceMapPathOverrides": {
  "webpack://_N_E/*": "${webRoot}/*"
}

I definitely did not need to do this back in the day (13.5.x for sure), so something must have regressed relatively recently.

Also struggling with this, can’t manage to make server side debugging work

I hope your thread can get some attention from the team – debugging is such a core part of development experience, it’s in everyone’s best interest to get this fixed and/or clarified ASAP. Best of luck with your scenario!

@albert-kovalevskij Had the solution for me. This only affects those using turborepo.

“P.S. https://nextjs.org/docs/pages/building-your-application/configuring/debugging just being stupid and not reading the docs, actually it worked perfectly by setting “cwd”: “${workspaceFolder}/apps/web” for turporepo”

Hi all, I just wanted to add what I’ve been using with the app router to get my debugging working as similar to the pages method in the docs. The main thing ive added compared to other suggestions is the ability to debug the full stack in one task.

Tested on Windows with WSL(ubuntu) and using the regular VSCode

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev --turbo"
    },
    {
      "name": "Next.js: debug client-side",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    },
    {
      "name": "Next.js: debug full stack",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev --turbo",
      "skipFiles": ["<node_internals>/**"],
      "sourceMaps": true,
      "sourceMapPathOverrides": {
        "/turbopack/[project]/*": "${webRoot}/*"
      },
      "serverReadyAction": {
        "action": "debugWithEdge",
        "killOnServerStop": true,
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "webRoot": "${workspaceFolder}"
      }
    }
  ]
}

It’s very surprising to me that client side, server side, and full-stack debugging is still not working 100% in Next.js 14 using the App Router.

Also the documentation (https://nextjs.org/docs/app/building-your-application/configuring/debugging) clearly is just a copy and paste of the stuff from the Pages Router. This suggests to me that debugging has not even been tested properly or prioritized.

To Vercel: Please revise the docs. Provide a launch.json that works with the latest version of VSCode. Also, please tell us with screenshots, videos, proper step-by-step on how to setup VSCode. Don’t just link to their docs. We as developers should not need to spend an entire day to figure out how to debug our Next.js applications.

Enough with the complains. I literally sat the entire day yesterday trying to figure out how the hell VSCode should be setup in order to get both client-side, server side and full-stack debugging properly without any hacky launch.jsons or other work-arounds. When I want to get something working I want to touch as little as possible of the IDE, settings file etc. So here’s my solution - it’s not perfect but it’s the most non-intrusive and one that I can live with in my day-to-day coding:

Client-Side, Server-Side, Full-Stack Debugging Next.js 14 (App Router) in VSCode

How to Debug (Client Side)

Note: It’s okay to have a regular Chrome browser open while debugging in VSCode. The debugger will attach to a NEW Chrome process that you launch from the terminal.

  1. Launch a new Chrome process from the terminal in VSCode by running the following command:

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222 --user-data-dir="/Users/your-user-goes-here/vscode-debugger-chrome-profile"

This command is no magic; it’s from the official VSCode docs: https://code.visualstudio.com/docs/nodejs/browser-debugging#_attaching-to-browsers

If this is the first time, Chrome will ask if you want to make this your current browser and if you want to send statistics to Google. Select whatever you want in this dialog.

The --user-data-dir flag is used in Chrome and Edge browsers to specify a custom directory for storing user data (such as cookies, local storage, browsing history, etc.) during the browser session. When you use this flag, the browser creates a new profile in the specified directory, separate from your default user profile. For debugging and to keep things isolated and not interfering with one another this is the recommended way.

  1. Create a launch.json file in VSCode and add the following configuration:

Note: You can autogenerate the code below by adding a new configuration and selecting “Chrome: Attach”. Also, you can copy and paste the code below in a new launch.json. Put the launch.json in your .vscode folder.

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Attach to Chrome",
            "port": 9222,
            "request": "attach",
            "type": "chrome",
            "webRoot": "${workspaceFolder}"
        }
    ]
}

  1. Open the Debugger in VSCode and select the “Attach to Chrome” configuration that you created in step 3.
  2. Set breakpoints in your code and run the debugger.

Note: I use Clerk as my auth provider and if you use this debugging method, signing in to your Google account via Clerk will work. If you use Nexj.js’s method (https://nextjs.org/docs/app/building-your-application/configuring/debugging#debugging-with-vs-code) you will not be able to sign in to your Google account. Keep this in mind when selecting debugging method.

How to Debug (Server Side)

  1. Create a new JavaScript Debug Terminal. (F1 and then type JavaScript Debug Terminal or create a new JavaScript Debug Terminal from your terminal pane by clicking the dropdown beside the plus sign.
  2. Run npm run dev
  3. Set some breakpoint in your .tsx components
  4. Use a regular Chrome window (with your own user profile) to navigate to the page you want to debug.
  5. The breakpoint will be unbound until you run that code in the browser. This is weird and unintuitive and should be improved somehow otherwise how else will you know that your breakpoints are working?

How to Debug (Full-stack)

I tried this by having two debugging sessions (client side and server side like I explained above) but it worked poorly so I would recommend using one method at a time and not both at once.

Notes:

In VSCode settings Debug -> JavaScript: Auto Attach Filter should be set to “Disabled” (This is the default setting). I messed around with this setting thinking it might solve some problems but I honestly don’t know how it works exactly so I wanted to make sure I reverted it back to its default setting.

I hope the above helps someone using Next.js 14+ (App Router) trying to debug both client side and server side code using VSCode’s debugger.

I’ve been unable to get next dev to properly start up with debugging enabled. If I use the launch config suggested in the docs, node simply isn’t launched with debugging enabled at all. If I try manually, eg:

$ npx --node-options='--inspect' next dev
Debugger listening on ws://127.0.0.1:9229/66073dfe-7554-4b37-8d8d-e4f7dc47789d
For help, see: https://nodejs.org/en/docs/inspector
Starting inspector on 127.0.0.1:9229 failed: address already in use

…this results in the parent next dev process running with debugging, but the worker subprocess tries to debug on the same port, which fails.

I was able to at least get debugging working by starting plain next dev with no debugging enabled, then sending SIGUSR1 to the next-router-worker subprocess spawned by the next dev process. I can then use VS Code to attach to the worker process.

This is a painful workaround; something in Next needs to be fixed to make debugging work properly.

Has there been any definitive progress towards a solution, or is there at least a workaround that doesn’t send us back in time?

I’ve spent two days trying to come up with a monorepo setup that supports:

  • hitting breakpoints in VSCode in monorepo packages
  • hot reloading
  • no red squiggles in VSCode

For a monorepo using Typescript, nextjs for the app, expressjs for the API server, and two basic packages. I swear this must be the most common configuration for people writing a frontend and backend in Typescript.

And yet. AND YET.

I got nowhere.

Got so annoyed I even went on a Twitter rant about it. You can see my continuing descent into madness in my personal open issue on it.

A very simple setup that got it working for me.

In package.json I specified Node inspect port option (default was busy by another project):

"scripts": {
    "dev": "NODE_OPTIONS='--inspect=9237' next dev"
  },

then I run my project npm run dev.

in launch.json :

    {
      "type": "node",
      "request": "attach",
      "name": "Attach to front-end",
      "port": 9238,   // note port is +1 of what's specified in inspect.
      "skipFiles": [
          "<node_internals>/**"
      ],
      "cwd": "${workspaceFolder}/front-end" // I have front-end dir in the workspace, use your setup
    },

And then run attach in VSCode. Breakpoints are working!

Note that ports do not match – I don’t know why but node was always starting on port+1 on specified!! (you can see actual port it started in the console).

Here to say that I finally got this working after a bunch of frustration (using node inspector, I don’t tend to use vscode for js debugging usually). The big key was this comment so thank you @dexxiez

Some notes on that

  • Firstly I had to run NODE_OPTIONS='--inspect' next dev
  • Then I pointed my browser to chrome://inspect and opened the inspector
  • I went to the connections tab and added one for localhost:9230
  • I shut down the server and then I shut down the inspector
  • I restarted the server in the same manner
  • Now in chrome://inspect I saw a second option screenshot of chrome inspect page showing two options now available
  • I clicked inspect on the second one (the one with start-server) and could actually find next’s server in start-server.js. This is promising since it runs in the same process as my code.
  • Now here’s the trick, this didn’t actually result in my code being visible in node inspector until I actually pointed my browser at the localhost:3000 app and let it load some pages. Only then could I CMD+P and find some of my typescript files. Once I did I could set breakpoints and those breakpoints get hit!

Therefore the trick seems to be to first of all add the appropriate connection, but then also to launch the process, let pages load, and only then try to connect to it via the debugger.

Update: I was able to make the fullstack debugger work 🎉

BUT the UX has confused me.

When setting the breakpoints and launching the debugger they look unbound. But then, they always get hit and I can debug properly.

On my side, client code, server components and server actions could be debugged properly.

Here’s my configuration:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug full stack",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/webapp/node_modules/next/dist/bin/next",
      "runtimeArgs": ["--inspect"],
      "skipFiles": ["<node_internals>/**"],
      "serverReadyAction": {
        "action": "debugWithChrome",
        "killOnServerStop": true,
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "webRoot": "${workspaceFolder}"
      },
      "cwd": "${workspaceFolder}/webapp"
    }
  ]
}

Thanks to @nomtats I was able to debug effectively 🎉

What worked for me was to put directly into my code the debugger directive:

Image

If you’re wondering here’s my launch.json config:

    {
      "name": "Next.js: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev",
      "cwd": "${workspaceFolder}/webapp",
    }

(Using cwd since I’m in a monorepo)

And here’s my package.json script section:

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

As you can see, I’m still using TurboPack which allows to compile faster.

I hope this helps some of you to debug until this issue is fixed!

This is how I got it working for Next.js 15.2:

{ // Use IntelliSense to learn about possible attributes. // Hover to view descriptions of existing attributes. // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 “version”: “0.2.0”, “configurations”: [ { “name”: “Next.js: Server”, “type”: “node-terminal”, “request”: “launch”, “command”: “npx next dev” }, { “name”: “Next.js: Client”, “type”: “chrome”, “request”: “launch”, “url”: “http://localhost:3000” } ], “compounds”: [ { “name”: “Debug Next.js (Client + Server)”, “configurations”: [“Next.js: Client”, “Next.js: Server”] } ] }

This issue is looking like my discussion here as well as my issue that I attempted to open here.

After PR https://github.com/vercel/next.js/pull/71940, merged in v15.0.3-canary.4, breakpoints no longer line up on server side code. The EvalSourceMapDevToolPlugin got changed from using a relative path to an absolute path. cc @icyJoseph

From what it looks like on this chat, people are working around the bug by trying to patch their webpack configurations.

I wrestled with it for a long time but couldn’t get it work no matter what sourceMapOverride I set.

I solved it eventually by calling npx next dev instead of pnpm dev. (Note that npx next dev --turbopack didn’t work.)

    {
      "name": "Next.js: Server",
      "type": "node-terminal",
      "request": "launch",
      "cwd": "${workspaceFolder}/apps/web",
      "command": "npx next dev",
      "env": {
        "NODE_OPTIONS": "--inspect"
      },
      "skipFiles": [
        "<node_internals>/**"
      ],
    },

Another thing that help was to add a debugger in the source code to force the debugger to break.

function() {
  // ....
  debugger;
  // ...
}

It seems the debugger confuses the code path thinking the source code is at apps/web/apps/web/... as opposed to just apps/web/. I don’t know why and couldn’t make it work with sourceMapOverride.

@tianzhich

Have you guys solved this in server-sider api debugging?

this set up it’s working for me. the only thing i didn’t manage to make it open the terminal in the editor code, so i have the debugger, but not the terminal

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug API (server-side)",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/next/dist/bin/next",
      "args": [
        "dev"
      ],
      "cwd": "${workspaceFolder}",
      "autoAttachChildProcesses": true,
      "skipFiles": [
        "<node_internals>/**"
      ],
      "serverReadyAction": {
        "pattern": "started server on .+? \\(http://.+?\\)",
        "uriFormat": "%s",
        "action": "openExternally"
      }
    }
  ]
}

thank you, i am using nextjs 15 and encounter issue when debugging server API, this code works for me! and yest the terminal does not open

@tianzhich

Have you guys solved this in server-sider api debugging?

this set up it’s working for me. the only thing i didn’t manage to make it open the terminal in the editor code, so i have the debugger, but not the terminal

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug API (server-side)",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/next/dist/bin/next",
      "args": [
        "dev"
      ],
      "cwd": "${workspaceFolder}",
      "autoAttachChildProcesses": true,
      "skipFiles": [
        "<node_internals>/**"
      ],
      "serverReadyAction": {
        "pattern": "started server on .+? \\(http://.+?\\)",
        "uriFormat": "%s",
        "action": "openExternally"
      }
    }
  ]
}

For people using

"dependencies": {
    "next": "14.2.14",
}

Here is what works for me:

{
  "version": "0.2.0",
  "compounds": [
    {
      "name": "Debug Start All",
      "configurations": ["Launch Chrome", "Start Nextjs"],
      "stopAll": true
    }
  ],
  "configurations": [
    {
      "type": "chrome",
      "request": "launch",
      "name": "Launch Chrome",
      "url": "http://localhost:3000",
      "webRoot": "${workspaceFolder}",
      "sourceMaps": true,
      "sourceMapPathOverrides": {
        "/turbopack/[project]/*": "${webRoot}/*"
      },
      "presentation": {
        "hidden": true
      }
    },
    {
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev",
      "name": "Start Nextjs",
      "sourceMaps": true,
      "sourceMapPathOverrides": {
        "/turbopack/[project]/*": "${webRoot}/*"
      },
      "presentation": {
        "hidden": true
      }
    }
  ]
}

thanks to https://github.com/vercel/next.js/issues/62008#issuecomment-2335459051

Thanks @dmitrc , and thank you for referencing #56702 which I found helpful too

I actually tried this and it still didn’t seem to pick things up. Keep in mind I’m specifically working with server files, e.g. route.ts files in this workflow. I’ve had some (limited) success grabbing Browser breakpoints.

To be doubly clear, I’m hoping to debug against server code in Next.js, not just the browser.

I’m wondering if there’s some other path to consider to include or index on the sourcemaps from route.ts files.

Update: I was able to make the fullstack debugger work 🎉

BUT the UX has confused me.

When setting the breakpoints and launching the debugger they look unbound. But then, they always get hit and I can debug properly.

On my side, client code, server components and server actions could be debugged properly.

Here’s my configuration:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug full stack",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/webapp/node_modules/next/dist/bin/next",
      "runtimeArgs": ["--inspect"],
      "skipFiles": ["<node_internals>/**"],
      "serverReadyAction": {
        "action": "debugWithChrome",
        "killOnServerStop": true,
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "webRoot": "${workspaceFolder}"
      },
      "cwd": "${workspaceFolder}/webapp"
    }
  ]
}

Thanks, tis worked for me 🥳 Not in a monorepo, here’s my config:

{
  "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": "debugWithChrome",
    "killOnServerStop": true,
    "pattern": "- Local:.+(https?://.+)",
    "uriFormat": "%s",
    "webRoot": "${workspaceFolder}"
  }
}

Also not seeing my server-side breakpoints light up, but they get hit and I can debug normally.

Still does not work with Turbopack in latest versions (on Windows):

$ npx create-next-app@latest --version
15.2.4
$ code --version
1.99.0
4437686ffebaf200fa4a6e6e67f735f3edf24ada
x64

With default settings, web app is using Turbopack:

$ npx create-next-app@latest --reset
$ npx create-next-app@latest

Server-side debugging with https://nextjs.org/docs/app/building-your-application/configuring/debugging settings do not work - breakpoints are not active. Setting "cwd": "${workspaceFolder}/apps/web" does not work because this folder does not exist, tried other paths, didn’t work.

If Turbopack is disabled during create-next-app then those debugging settings from docs work out of the box.

{
            "name": "Next.js: debug full stack",
            "program": "${workspaceFolder}/my-app/node_modules/next/dist/bin/next",
            "args": [
                "dev",
                "--turbopack",
            ],
            "runtimeArgs": [
                "--inspect"
            ],
            "skipFiles": [
                "<node_internals>/**",
            ],         
            "type": "node",
            "request": "launch",
            "sourceMaps": true,
            "serverReadyAction": {
                "killOnServerStop": true,
                "webRoot": "${workspaceFolder}/my-app",
                "pattern": "- Local:.+(https?://.+)",
                "uriFormat": "%s",
                "action": "debugWithChrome"
            },
            "sourceMapPathOverrides": {
                "file://C%3A/WORK/VSCODE/PROJECTS/my-app/*": "${workspaceFolder}/my-app/*",
                "start-server.js/*": "${workspaceFolder}/*",
            },
            "cwd": "${workspaceFolder}/my-app",
        }

After try and errors this works for me with --turbopack. Im not actually sure why and how. This is my first attempt to debug nextjs with actual debugger instead of console.log.

“file://C%3A/WORK/VSCODE/PROJECTS/my-app/": "${workspaceFolder}/my-app/”

I figured out that when i run with turbo, i get encoded C%3A instead of C: in chrome dev tools -> sources. So this line fixed client side debugging. But server side didnt work.

Then i check vscode “Loaded Scripts” tab. Notice that files i need to debug stored in - Next.js: debug full stack -> start-server.js -> my-app -> src -> app so i put

“start-server.js/": "${workspaceFolder}/”

and it works for me.

Client side is related to #73384 i think. And server side is more like #62008, but instead of turbopack i get start-server.js

So check your “dev-tools -> sources” and vscode Loaded Scripts for client and server side files and adjust path in overrides accordingly.

Thanks @TechGeorgii for your post, I was bashing my head against a wall b/c the attach to port option used to work for me then stopped after some upgrades. The trick for me was your comment :

“port”: 9238, // note port is +1 of what’s specified in inspect.

I have the following in package.json : --inspect=9231

I switched my attach to port config to use 9232 and it worked! Development accelerated! Debug config for those who want to try it out :

            {
                "type": "node",
                "request": "attach",
                "name": "Node - Attach to Port",
                "port": 9232,
                "skipFiles": [
                    "<node_internals>/**"
                ]
            },

For anyone using > Next.js 14.2, the source map path has changed, per https://github.com/vercel/next.js/issues/63740#issuecomment-2074742942:

        // Old Turbopack path
        "/turbopack/[project]/*": "${workspaceFolder}/*",
        // New Turbopack path
        "turbopack://[project]/*": "${workspaceFolder}/*"

I’m running the 14.2.3 canary and breakpoint debugging suddenly broke. Changing the sourceMapPathOverrides path like above fixed it for me.

In all scenarios debugger attaches for me just fine but breakpoints do not bind. I’m guessing is just related to it being unable to find the files. I’m using these configs:

{
      "name": "Next.js: Attach",
      "port": 9230,
      "request": "attach",
      "skipFiles": ["<node_internals>/**"],
      "type": "node",
      "localRoot": "${workspaceFolder}/my-app/src"
    },
    {
      "name": "Next.js: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev",
      "sourceMaps": true,
      "sourceMapPathOverrides": {
        "webpack://_N_E/*": "${webRoot}/*"
      },
      "cwd": "${workspaceFolder}/may-app"
    },

Nothing seems to work

https://github.com/vercel/next.js/issues/62008#issuecomment-1943221232

Just so y’all know, this did not work for me. @dmitrc did this work for you with API endpoints (not just the actual page.tsx files?)

@andrewmartin, just to confirm, while the other thread is named “client-side debugging”, for my case I was actually also looking to fix the issues with debugging server files specifically (page.tsx), and following the steps outlined above helped.