How to Debug Node.js Applications with Built-in Inspector and CLI Tools

Apr 14, 2026

Debugging code editor

When I started with Node.js, I relied heavily on console.log everywhere. My code looked like this:

function processData(data) {
  console.log('Input:', data);
  const result = transform(data);
  console.log('Result:', result);
  return result;
}

This approach gets messy fast. The console fills with logs, and finding the actual issue becomes harder. Node.js has built-in debugging tools that work better than scattered console.log statements.

Environment

Node.js v18+
Chrome browser (for DevTools debugging)
Terminal access

What happened?

I was debugging a slow API endpoint. The function processed user data but sometimes returned undefined. Adding console.log everywhere made the code harder to read, and I couldn’t pause execution to inspect variables at specific points.

Here’s the problematic code:

async function handleRequest(req, res) {
  const userData = await fetchUser(req.params.id);
  const processed = processData(userData);
  // Where is the issue? console.log everywhere?
  res.json(processed);
}

How to solve it?

Solution #1: CLI debugging with node inspect

Node.js includes a built-in CLI debugger. I tried this first:

node inspect app.js

This starts the debugger and pauses at the first line. The output looks like:

< Debugger listening on ws://127.0.0.1:9229/...
< For help, see: https://nodejs.org/en/docs/inspector
debug>

I added debugger statements in my code to set breakpoints:

async function handleRequest(req, res) {
  debugger; // Pause here
  const userData = await fetchUser(req.params.id);
  debugger; // Pause after fetch
  const processed = processData(userData);
  res.json(processed);
}

Then I ran with node inspect and used these commands:

cont or c - continue execution
next or n - step to next line
step or s - step into function
out or o - step out of function
repl - enter REPL to inspect variables

At each breakpoint, I typed repl to check variable values:

debug> repl
Press Ctrl + C to leave debug repl
> userData
{ id: 123, name: 'Test User' }
> processed
undefined

I found that processData returned undefined when input had no name field.

Solution #2: Chrome DevTools with —inspect flag

CLI debugging works, but visual debugging is easier. I started Node.js with the inspector flag:

node --inspect app.js

Or to pause immediately at startup:

node --inspect-brk app.js

The output shows:

Debugger listening on ws://127.0.0.1:9229/abc123...
For help, see: https://nodejs.org/en/docs/inspector

Then I opened Chrome and navigated to chrome://inspect. The DevTools window appeared with my Node.js process listed.

Clicking “inspect” opened the full DevTools interface:

Sources panel shows my code
Clicking line numbers sets breakpoints
Variables panel shows current values
Call stack shows function chain

I set breakpoints by clicking line numbers, then triggered the API request. DevTools paused at each breakpoint, showing variable values clearly.

The reason

I think the key reasons to use built-in debugging:

Works anywhere - No IDE required. Debug on servers, containers, or CI pipelines.
Better than console.log - Pause execution, inspect all variables, step through code line by line.
Inspector protocol - The --inspect flag opens a WebSocket that any debugger can connect to. VS Code, Chrome, and other tools use this protocol.
debugger statement - Adding debugger; in code creates breakpoints that work in both CLI and DevTools.

Common mistakes I made

Using only console.log - Hard to trace complex issues, cluttering the codebase
Not knowing —inspect-brk - --inspect runs immediately, --inspect-brk pauses at first line for debugging startup issues
Ignoring async debugging - Async functions need stepping through properly; the debugger handles this but requires patience

Summary

In this post, I showed how to use Node.js built-in debugging tools. The key point is you can debug effectively with node inspect and --inspect flags without installing any IDE extensions. This skill works across all environments and is essential for Node.js troubleshooting.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Node.js Debugger Documentation
👨‍💻 Node.js Inspector Protocol

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!