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

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

vvo profile image Vincent Voyer Updated on ・5 min read

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

πŸ‘‹ Hi there, this article explains how to setup your developer environment so you can debug your Next.js application using Visual Studio Code debugger or Chrome DevTools.

Since Next.js is a Node.js application, what's provided here as guidance will also work for any Node.js program.

When fully setup, you'll be able to put breakpoints in both frontend (React) and backend code (Node.js, API routes). Then your favorite debugger will pop out whenever your code encounters your breakpoints.

The whole tutorial takes 5 min. When you'll be finished, you'll get this experience (VS Code, React):

Demo of a Visual Studio Code debugging session in Next.js frontend code

Table of contents:

Mandatory introduction: why even bother?

I always thought that I don't need a debugger in JavaScript: I can just console.log my way out most of the time. The reason for this habit I believe is that JavaScript debugging tools were always kind of working but not really. In the browser at least it was working but then Node.js came and it was again very hard to debug it nicely. The whole debugging experience was painful and you spent more time switching windows than anything else.

Now after using VS Code to debug both my React and Node.js code I really think it's way more powerful than a regular console.log(obj) > reload page > switch to a terminal (πŸ” repeat with console.log(obj.property...) flow.

Give it a try, you'll "enjoy" it.

I will be using a fresh create-next-app example to demonstrate how it works.

Step one: create your Next.js debugging demo application

You can skip to step two if you already have a Next.js application

in a terminal:

> npx create-next-app
βœ” What is your project named? … demo-nextjs-debugging
# wait...
> cd create-next-app

Step two: configure Next.js to start in debug mode

Edit the file package.json and change this part:

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

If you have a different way of launching Next.js, just make sure that NODE_OPTIONS='--inspect' is always right before the next command.

I like to change the default dev command so that anytime I am in developer mode, I can start a debugging session in one shortcut (more on that in step four).

Be aware that using NODE_OPTIONS='--inspect' npm run dev or NODE_OPTIONS='--inspect' yarn run dev won't work. This would try to start multiple debuggers on the same port: one for the npm/yarn process and one for Next.js. You would then get an error like Starting inspector on failed: address already in use in your console.

NODE_OPTIONS is a standard Node.js flag.

Step three: launch your application

in a terminal:

> yarn dev
yarn run v1.22.0
$ NODE_OPTIONS='--inspect' next dev
Debugger listening on ws://
For help, see: https://nodejs.org/en/docs/inspector
[ wait ]  starting the development server ...
[ info ]  waiting on http://localhost:3000 ...
[ ready ] compiled successfully - ready on http://localhost:3000

Step four: connect your debugging inspector

This is a convoluted title but it just means connecting either VS Code debugging feature or Chrome DevTools to your Next.js application.

VS Code

You can also skip to the chosen solution.

There are multiple ways to connect the VS Code inspector to your Next.js application running in debug mode. All of that is explained in VS Code gigantic Node.js debugging documentation page.

You can either:

  1. Configure VS Code to actually start your Next.js application for you and connect to its debugger. Frankly, this is not my favorite solution because usually all developer environments are already using some sort of process manager like node-foreman, ❀️ overmind, docker-compose, heroku local, nodemon. So... No!
  2. Start your Next.js application from within the internal terminal of VS Code so it detects it. Same as 1., I don't use the internal VS Code terminal, I have a side terminal already.
  3. Configure VS Code so that it connects to your already started Next.js application. βœ… That's what I like.

Here's how to do it:

Create .vscode/launch.json at the root of your project:

  "version": "0.2.0",
  "configurations": [
      "type": "node",
      "request": "attach",
      "name": "Launch Program",
      "skipFiles": [
      "port": 9229

Save it. Now hit F5 on your keyboard or go click on "Run and Debug (F5)" in the 🐞 debugging panel of VS Code. You should get this:

Example of a debugging session in VS Code

As you can see, you now have the full VS Code inspector connected to your Next.js application. It even shows the console output.

Now, whenever you think "Hmm, I wonder what's not working, what does this variable really holds". Just hit F5 in VS Code, trigger the underlying code (page refresh, click..) and enjoy a nice debugging experience!

Bonus: If your Next.js code is not at the root of your workspace

If your Next.js project is not at the root of your VSCode workspace, then you need to add:


  // ...
  "configurations": [
      // ...
      "sourceMapPathOverrides": {
        "webpack:///./*": "${workspaceRoot}/subfolder/*",

Thanks ubermensh for the tip!

Chrome DevTools

If you prefer to debug your Next.js application using the regular Chrome DevTools, all you have to do now is open a new tab in Chrome with the url being: chrome://inspect.

You'll see this:

Alt Text

Click on "inspect" and the Chrome DevTools are now connected to your Next.js application.

Step five: actually debug your application

Now all you have to do is setup breakpoints in your application. Either by adding the debugger; keyword anywhere in your code or by clicking on the left of a line to turn it into a breakpoint in VS Code editor or Chrome.

Whenever you do so and the underlying code runs (page load, page click, api call...) then a debugging UI will popup.

How to use VS Code or Chrome debugging tools is better explained by their own docs:

πŸ”š That's it!

πŸ™ Thank you for reading.

Did you enjoy this post? Any advice as for Next.js or Node.js debugging? Add a thank you note or advice in the comments and I'll reply :)

Click below to share this post:

Posted on Mar 4 by:

vvo profile

Vincent Voyer


🌱 Growing indie hacker. Previously: JavaScript APIs @ algolia.com


markdown guide

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 failed: address already in use


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!


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://
For help, see: https://nodejs.org/en/docs/inspector
[ wait ] starting the development server ...
[ info ] waiting on http://localhost:3000 ...
Starting inspector on failed: address already in use
Starting inspector on failed: address already in use
Starting inspector on 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

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

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!


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


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


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://
For help, see: https://nodejs.org/en/docs/inspector
[ wait ]  starting the development server ...
[ info ]  waiting on http://localhost:3000 ...
Starting inspector on failed: address already in use
Starting inspector on failed: address already in use...

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?


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 Β πŸ™


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


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

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.


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!

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

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


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

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

What I wanted to say is that:


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.


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


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:

Thank you :)


I figured it out,

  1. Change your next dev script to the following (same as you mentioned in your tutorial)
    "scripts": {
    "dev": "NODE_OPTIONS='--inspect' next",

  2. Create a JS Debug config (see blog.jetbrains.com/webstorm/2017/0...)

  3. Remember to update Google Chrome! I didn't do this and it's what messed me up.


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;


It looks like the problem with NODE_OPTIONS has been fixed, I'm not getting the Starting inspector on 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!


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.


IF someone else struggling with this: if your next project is in subfolder in your vscode workspace, you should use sourceMapPathOverrides


Nice, adding this to the post, thanks!


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"


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...