DEV Community

5 Steps to debugging Next.js/Node.js from VSCode or Chrome DevTools

Vincent Voyer on March 04, 2020

April 5, 2020 update: This article is now part of the Next.js documentation: https://nextjs.org/docs/advanced-features/debugging 👋 Hi there, th...

Read full post

pom421 • Mar 26 '20 • Edited

It just doesn't work :(.

On a Mac OS, with create-next-app in version 9.1.1.

npx create-next-app
"scripts": { "dev": "NODE_OPTIONS='--inspect' next",
I run yarn dev and terminal displays:

$ NODE_OPTIONS='--inspect' next Starting inspector on 127.0.0.1:9229 failed: address already in use

Vincent Voyer • Mar 26 '20

Hey there, there's currently a bug in Next.js about this, I opened a PR here: github.com/zeit/next.js/pull/11041

I updated the blog post too.

But in Next.js 9.1.1 it should have been working weirdly. Are you starting different Node.js processes from Next.js? Or maybe you have a Next.js plugin that is doing so. Let me know!

pom421 • Mar 26 '20 • Edited

Thanks for the quick answer.

This is the package.json after npx create-next-app:

{ "name": "test", "version": "0.1.0", "private": true, "scripts": { "dev": "NODE_OPTIONS='--inspect' next dev", "build": "next build", "start": "next start" }, "dependencies": { "next": "9.3.1", "react": "16.13.1", "react-dom": "16.13.1" } }

Everything seems up to date, yet :

yarn dev

yarn run v1.22.0 $ NODE_OPTIONS='--inspect' next dev Debugger listening on ws://127.0.0.1:9229/dc491c88-ca40-47d2-8568-26ea554a4ae4 For help, see: https://nodejs.org/en/docs/inspector [ wait ] starting the development server ... [ info ] waiting on http://localhost:3000 ... Starting inspector on 127.0.0.1:9229 failed: address already in use Starting inspector on 127.0.0.1:9229 failed: address already in use Starting inspector on 127.0.0.1:9229 failed: address already in use

And when I inspect for the port 9229, nothing is bound to.
lsof -nP -iTCP:9229 | grep LISTEN -> no line

Vincent Voyer • Mar 26 '20

Hey there, can you try with next@9.2? I know this version was working because I used the debugging on it.

pom421 • Mar 26 '20

Good guess! It works with Next 9.2.0 and not in 9.3.1...

I will wait for your PR to be merged so, because I don't want to downgrade the version for this only debug need.

Thanks for your help!

Sambhav Gore • Jun 4 '20 • Edited

I followed it exactly but could not get it to work.
Shows Debugger attached, but when I add breakpoints, it stops at other code places which is not my code and stepping through just goes past where I wanted it to stop.
If I enter debugger; statements they are simply ignored. it never stops on those.

I am on nextjs 9.4.0 with node 13.13.0 and latest VSCode on Ubuntu 18.04

Helmut Drewes • Jun 25 '20

Did you manage to solve the issue. Have exactly the same problem.

Sambhav Gore • Jun 25 '20

no I did not.

Roman Kraiovsky 🇺🇦🇸🇪 • Apr 7 '20

Hey, thanks for the post!
It works well with Next front-end, but setting breakpoints in VS Code for APIs does not work - VS Code complains "Breakpoint set but not yet bound". Setting debugger does work though.
Do you know why and how to make IDE breakpoints work?

Vincent Voyer • Apr 8 '20

Hmm it's weird, following the exact same guide I do have breakpoints in API routes working well. So really don't know what to tell you.. Try to create a simple repository and see if you're having the same issue, share it with me and I will also test it.

Thanks 🙏

S.R. Aman • May 19 '20

Hey, Great article.
But I don't think it is working as of now.
I am still getting

> NODE_OPTIONS='--inspect' next

Debugger listening on ws://127.0.0.1:9229/2b4b791d-9654-4de5-9226-c2816116b1ac
For help, see: https://nodejs.org/en/docs/inspector
[ wait ]  starting the development server ...
[ info ]  waiting on http://localhost:3000 ...
Starting inspector on 127.0.0.1:9229 failed: address already in use
Starting inspector on 127.0.0.1:9229 failed: address already in use...

Ramiro Herrera • May 9 '20

Hi there, thanks for making this guide :)

I'm stuck at step three with the following error in console

'NODE_OPTIONS' is not recognized as an internal or external command,
operable program or batch file.
error Command failed with exit code 1.

I solved following the steps on this post stackoverflow.com/questions/539485... and replacing the dev config with this one: "dev": "cross-env NODE_OPTIONS='--inspect' next",

My problem is, debugger doesn't seem to work. I used the same breakpoints, the same 'test' variable as in the video example, but I get nothing on my debugger tabs (variables, watch, etc.) when I run it

Stuart Tett • Sep 16 '20

I'm constantly having this issue with debugging Next.js API routes. Often I can't place breakpoints in vscode, or if I do it breaks at some totally random spot (sometimes it will open the correct transpiled file and then I can just move the breakpoint to where it should be).

The only chance I have is to stop my server, restart vscode, blow away the the .next directory, and restart. But as soon as I change some code, I have to do it all over again.

I feel like there must be some trick to it, otherwise, I feel like i'd see more complaints about it.

{
      "type": "node",
      "request": "attach",
      "name": "Attach to Program",
      "skipFiles": [
        "<node_internals>/**"
      ],      
      "port": 9229
    },

"dev": "NODE_OPTIONS='--inspect' next dev",

Pinesh I Menat • Jun 16 '21

My Two cents:

NextJS under the hood is ReactJS so I tried adding launch.json of react from VSCode

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

Now run NextJS as "dev": "next dev" - no change
npm run dev
Press F5 to attch the process and it should work now.

Ricardo Martins • Nov 29 '22

Vscode always stop at the first line, no matter what you configure it to.

It ignores the skipFiles, stopOnEntry, etc.

Any idea why?

Eunjae Lee • Jun 8 '20

I don't know the exact difference, but for those of you who get address already in use issue,

try

"dev": "node --inspect node_modules/.bin/next",

Vincent Voyer • Jun 9 '20

Hi there, which command were you using previously when getting "address already in use"? The blog post and documentation warns about this so I thought it would be good. The error comes from the fact that NODE_OPTIONS is sent to all child node processes so when running NODE_OPTIONS=.. yarn dev you're asking yarn to start in debugger mode and also nextjs, on the same port, which causes this error.

Also, you should be able to safely remove node_modules/.bin/ because that's already the default when running npm scripts.

Eunjae Lee • Jun 9 '20

Hey, embarrassingly, I do not remember which command I was using yesterday. (It was literally yesterday, though)

anyway you're saying

NODE_OPTIONS='--inspect' next
node --inspect node_modules/.bin/next

These two commands are equivalent?
I didn't know. Thank you!

Vincent Voyer • Jun 9 '20

I do not know if both of those commands are equivalent, what I know is that:

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

and

{
  "scripts": {
    "dev": "./node_nodules/.bin/next"
  }

are equivalent, because of: docs.npmjs.com/misc/scripts#path

What I wanted to say is that:

running

NODE_OPTIONS='--inspect' yarn dev

will fail because this starts two processes in debugger mode: yarn and nextjs. This is why you get the error message about already running debugging server.

NODE_OPTIONS can only be passed right next to the next command inside package.json.

Victor Cheeney • Apr 1 '20

It looks like the problem with NODE_OPTIONS has been fixed, I'm not getting the Starting inspector on 127.0.0.1:9229 failed: address already in use error anymore. 🙂 However, I can't seem to get the clientside debugging working. I installed the Debugger for Chrome extension in VS Code, but I think that I miss a certain launch.json attach configuration? Excellent tutorial, thank you!

Vincent Voyer • Apr 2 '20

Yes you do need a launch.json configuration, and I don't think you need a particular extension on VSCode, just the regular current installation.

The launch.json configuration is inside the blog post, did you use it?

You can also first try the Google Chrome debugging method also highlighted in this blog post which requires less configuration.

ubermensh • Apr 4 '20 • Edited

Another potential pitfall (I hit them all, and seems that I finally got it working somehow)

If chrome debugging doesn't work in VSCode, you may need a different type of source map, alter your next.config.js
module.exports = {
webpack(config) {
config.devtool = 'cheap-module-eval-source-map';
return config;
}
};
spectrum.chat/next-js/general/debu...

Jordan Réjaud • Apr 10 '20

Bonjour Vincent,

Excellent tutorial, thank you.

Could you write one that explains how to do the same with Webstorm instead of VS Code?

Similar to how Webstorm lets you debug React apps:
blog.jetbrains.com/webstorm/2017/0...

Thank you :)

Jordan Réjaud • Apr 10 '20

I figured it out,

Change your next dev script to the following (same as you mentioned in your tutorial)
"scripts": {
"dev": "NODE_OPTIONS='--inspect' next",
}
Create a JS Debug config (see blog.jetbrains.com/webstorm/2017/0...)
Remember to update Google Chrome! I didn't do this and it's what messed me up.

ubermensh • Apr 3 '20

IF someone else struggling with this: if your next project is in subfolder in your vscode workspace, you should use sourceMapPathOverrides
stackoverflow.com/a/61013488/1793469

Vincent Voyer • Apr 3 '20

Nice, adding this to the post, thanks!

AW A RE • Sep 19 '20 • Edited

NODE_OPTIONS='--inspect' next, is not working.

try this: "dev": "node --inspect ./node_modules/next/dist/bin/next",

But debugger is not working anyway.

ubermensh • Apr 3 '20

This is not working with next 9.3
debugger in source code will fire in dev tools, and not in vscode. the breakpoints in vscode is greyd out, says 'brakepoint set but not yet bound"

Vincent Voyer • Apr 3 '20

Hey there, I am using the latest VScode, latest Next.js and everything is working fine. I can either debug in Chrome dev tools or in VScode, using debugger; keyword or breakpoints by click in VScode

⚠️ You either activate the Dev tools debugger (Google Chrome) OR the one in VScode, but not both at the same time. As soon as you activate the one in Chrome, then it will disable it in VSCode.

I commented on the PR with screenshots of it working in VSCode: github.com/zeit/next.js/pull/10807...