Debugging Node.js Applications

Effective debugging saves hours of frustration. Here's how to debug Node.js applications like a pro.

Console Methods#

// Beyond console.log
const user = { id: 1, name: 'John', email: 'john@example.com' };
const users = [user, { id: 2, name: 'Jane' }];

// Formatted output
console.log('User:', user);
console.log('User: %o', user);  // Object format
console.log('Name: %s, ID: %d', user.name, user.id);

// Table format for arrays/objects
console.table(users);
console.table(users, ['id', 'name']);  // Specific columns

// Grouped output
console.group('User Details');
console.log('ID:', user.id);
console.log('Name:', user.name);
console.groupEnd();

// Collapsed group
console.groupCollapsed('Debug Info');
console.log('Detailed info here');
console.groupEnd();

// Timing
console.time('fetchData');
await fetchData();
console.timeEnd('fetchData');  // fetchData: 150.23ms

// Count calls
function processItem() {
  console.count('processItem called');
}

// Stack trace
console.trace('Where am I?');

// Assertions
console.assert(user.id > 0, 'User ID should be positive');

// Clear console
console.clear();

Node.js Inspector#

# Start with inspector
node --inspect app.js

# Break on first line
node --inspect-brk app.js

# Custom port
node --inspect=9230 app.js

# Connect Chrome DevTools
# Open chrome://inspect in Chrome
# Click "inspect" under Remote Target

// Programmatic breakpoints
function processData(data) {
  debugger;  // Pauses here when inspector connected
  return transform(data);
}

// Conditional breakpoint in DevTools
// Right-click line -> Add conditional breakpoint
// Enter condition: data.length > 100

VS Code Debugging#

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Current File",
      "type": "node",
      "request": "launch",
      "program": "${file}",
      "skipFiles": ["<node_internals>/**"]
    },
    {
      "name": "Debug Application",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/src/index.ts",
      "preLaunchTask": "tsc: build",
      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
      "env": {
        "NODE_ENV": "development"
      }
    },
    {
      "name": "Debug Tests",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/jest/bin/jest",
      "args": ["--runInBand", "--no-cache"],
      "console": "integratedTerminal"
    },
    {
      "name": "Attach to Process",
      "type": "node",
      "request": "attach",
      "port": 9229
    }
  ]
}

Error Handling Debug#

// Catch uncaught exceptions
process.on('uncaughtException', (error) => {
  console.error('Uncaught Exception:', error);
  console.error('Stack:', error.stack);
  process.exit(1);
});

// Catch unhandled promise rejections
process.on('unhandledRejection', (reason, promise) => {
  console.error('Unhandled Rejection at:', promise);
  console.error('Reason:', reason);
});

// Async stack traces (Node 12+)
// Run with: node --async-stack-traces app.js

// Error with cause
function fetchUser(id: string) {
  try {
    return db.query(`SELECT * FROM users WHERE id = $1`, [id]);
  } catch (error) {
    throw new Error(`Failed to fetch user ${id}`, { cause: error });
  }
}

// Log full error chain
function logErrorChain(error: Error, depth = 0) {
  console.error('  '.repeat(depth) + error.message);
  if (error.cause) {
    logErrorChain(error.cause as Error, depth + 1);
  }
}

Memory Debugging#

// Check memory usage
function logMemory() {
  const used = process.memoryUsage();
  console.log({
    heapTotal: `${Math.round(used.heapTotal / 1024 / 1024)} MB`,
    heapUsed: `${Math.round(used.heapUsed / 1024 / 1024)} MB`,
    external: `${Math.round(used.external / 1024 / 1024)} MB`,
    rss: `${Math.round(used.rss / 1024 / 1024)} MB`,
  });
}

// Periodic memory logging
setInterval(logMemory, 5000);

// Heap snapshot
const v8 = require('v8');
const fs = require('fs');

function takeHeapSnapshot() {
  const snapshotStream = v8.writeHeapSnapshot();
  console.log('Heap snapshot written to:', snapshotStream);
}

// Trigger with signal
process.on('SIGUSR2', takeHeapSnapshot);

// Force garbage collection (run with --expose-gc)
if (global.gc) {
  global.gc();
  console.log('Garbage collection triggered');
}

# Run with memory debugging
node --expose-gc --max-old-space-size=4096 app.js

# Generate heap snapshot on OOM
node --heap-prof app.js

# Analyze with Chrome DevTools Memory tab

Performance Profiling#

// Built-in profiler
const { performance, PerformanceObserver } = require('perf_hooks');

// Measure function execution
performance.mark('start');
await expensiveOperation();
performance.mark('end');
performance.measure('operation', 'start', 'end');

// Observer for measurements
const obs = new PerformanceObserver((items) => {
  items.getEntries().forEach((entry) => {
    console.log(`${entry.name}: ${entry.duration}ms`);
  });
});
obs.observe({ entryTypes: ['measure'] });

// Wrap function for timing
function withTiming<T>(name: string, fn: () => T): T {
  const start = performance.now();
  try {
    return fn();
  } finally {
    console.log(`${name}: ${(performance.now() - start).toFixed(2)}ms`);
  }
}

// Async version
async function withTimingAsync<T>(
  name: string,
  fn: () => Promise<T>
): Promise<T> {
  const start = performance.now();
  try {
    return await fn();
  } finally {
    console.log(`${name}: ${(performance.now() - start).toFixed(2)}ms`);
  }
}

# CPU profiling
node --prof app.js
node --prof-process isolate-*.log > profile.txt

# Generate flamegraph
node --perf-basic-prof app.js
# Use perf and flamegraph tools

Debug Library#

import debug from 'debug';

// Create namespaced loggers
const logApp = debug('app');
const logDb = debug('app:db');
const logApi = debug('app:api');
const logAuth = debug('app:auth');

// Usage
logApp('Application starting');
logDb('Connected to database');
logApi('Request received: %O', { method: 'GET', path: '/users' });
logAuth('User authenticated: %s', userId);

// Enable via environment variable
// DEBUG=app:* node app.js       // All app logs
// DEBUG=app:db node app.js      // Only db logs
// DEBUG=app:db,app:api node app.js  // Multiple
// DEBUG=* node app.js           // Everything

// In code
debug.enable('app:db');
debug.disable('app:api');

Network Debugging#

// Log all HTTP requests
import http from 'http';

const originalRequest = http.request;
http.request = function (options, callback) {
  console.log('HTTP Request:', {
    method: options.method || 'GET',
    host: options.host || options.hostname,
    path: options.path,
  });
  return originalRequest.apply(this, arguments);
};

// Axios interceptors
import axios from 'axios';

axios.interceptors.request.use((config) => {
  console.log('Request:', config.method?.toUpperCase(), config.url);
  return config;
});

axios.interceptors.response.use(
  (response) => {
    console.log('Response:', response.status, response.config.url);
    return response;
  },
  (error) => {
    console.error('Request failed:', error.message);
    return Promise.reject(error);
  }
);

Best Practices#

General:
✓ Use structured logging
✓ Add context to errors
✓ Use debug namespaces
✓ Remove debug code before production

Tools:
✓ Master VS Code debugger
✓ Learn Chrome DevTools
✓ Use source maps
✓ Profile before optimizing

Memory:
✓ Monitor memory usage
✓ Take heap snapshots
✓ Check for event listener leaks
✓ Review closure references

Effective debugging combines multiple techniques. Use console methods for quick checks, the inspector for complex issues, and profiling tools for performance. Structure your logging with namespaces and levels to quickly isolate problems in production.