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

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

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.

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.

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

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.

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.

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.

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}"
      }
    }
  ]
}

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.

@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”

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!