Introduction
Debugging is the process of finding and fixing defects in code. Node.js ships with a built-in inspector protocol that allows developers to pause execution, step through code, and inspect variables using tools like Chrome DevTools, VS Code, or the command-line debugger, going far beyond simple console.log statements.
Cricket analogy: Debugging is like a third umpire reviewing a run-out in slow motion — instead of just trusting the on-field call (console.log), you pause the replay frame by frame, inspect the bail and the batsman's bat exactly at contact, using DRS tools built for that purpose.
Syntax
// Start Node with the inspector enabled
node --inspect index.js
// Break immediately on the first line
node --inspect-brk index.js
// Insert a programmatic breakpoint in code
function processOrder(order) {
debugger; // execution pauses here when inspector is attached
return order.total * 1.1;
}Explanation
Running node --inspect index.js starts the app and opens a WebSocket debugging port (default 9229) that Chrome DevTools can attach to by navigating to chrome://inspect. The --inspect-brk flag pauses execution on the very first line, useful for debugging startup code. The debugger; statement acts as a breakpoint directly in source code. Beyond console.log, the console object offers console.error() and console.warn() for severity-differentiated output, console.table() for tabular data, console.time()/console.timeEnd() for measuring execution duration, and console.trace() to print a stack trace at a given point.
Cricket analogy: Starting node --inspect is like opening a dedicated broadcast feed on channel 9229 for the third umpire; --inspect-brk freezes the very first ball of the innings before it's even bowled; a debugger; statement is a marked stump you plant to force a review at that exact ball; console.table is like a full scorecard grid, and console.time/timeEnd clocks exactly how long a review took.
Example
function calculateTotal(items) {
console.time('calculateTotal');
debugger; // pause here with node --inspect-brk
let total = 0;
for (const item of items) {
if (typeof item.price !== 'number') {
console.warn('Invalid price for item:', item);
continue;
}
total += item.price * item.quantity;
}
console.table(items);
console.timeEnd('calculateTotal');
return total;
}
const cart = [
{ name: 'Book', price: 12.5, quantity: 2 },
{ name: 'Pen', price: 'free', quantity: 5 },
];
try {
console.log('Total:', calculateTotal(cart));
} catch (err) {
console.error('Failed to calculate total:', err);
}Output
When run with node --inspect-brk example.js, Chrome DevTools (opened via chrome://inspect) attaches and execution halts at the debugger statement, letting you step through line by line, inspect the items array, and watch total accumulate. Without the inspector, the script logs a warning for the invalid price, prints a formatted console.table of items, reports the elapsed time from console.timeEnd, and finally logs the computed total.
Cricket analogy: Running with --inspect-brk, the third umpire freezes at the debugger statement, steps through each delivery in the over one by one, and watches the run total accumulate; without it, the system just flags an invalid extra, prints the full over as a table, times the review, and logs the final total.
Key Takeaways
- node --inspect enables remote debugging; node --inspect-brk pauses on the first line of the script.
- The debugger; statement creates a breakpoint that pauses execution when the inspector is attached.
- console offers more than log(): error(), warn(), table(), time()/timeEnd(), and trace() aid debugging.
- Chrome DevTools can attach to a running Node process via chrome://inspect for full step-through debugging.
Practice what you learned
1. Which Node.js flag pauses script execution at the very first line for debugging?
2. What does the debugger; statement do when the Node inspector is not attached?
3. Which console method displays array or object data in a formatted table?
4. How do you attach Chrome DevTools to a Node process started with --inspect?
Was this page helpful?
You May Also Like
Testing Node Apps with Jest
Learn to write unit and integration tests for Node.js and Express apps using Jest and Supertest.
Logging in Node.js Apps
Learn why console.log is insufficient in production and how to implement structured logging with Winston or Pino.
Node.js Performance Optimization
Learn how to scale Node.js apps with the cluster module, avoid blocking the event loop, and apply caching strategies.
Related Reading
Related Study Notes in Web Development
Browse all study notesWebSockets Study Notes
Web Development · 30 topics
Web DevelopmentWebAssembly Study Notes
WebAssembly · 30 topics
Web DevelopmentgRPC Study Notes
Protocol Buffers · 30 topics
Web DevelopmentSpring Boot Study Notes
Java · 30 topics
Web DevelopmentFlask Study Notes
Python · 30 topics
Web DevelopmentDjango Study Notes
Python · 30 topics