Master error handling patterns, debugging techniques, and logging in Node.js applications.
Error Handling & Debugging
Robust error handling is what separates amateur applications from production-ready systems. In this chapter, you’ll learn how to handle errors gracefully, debug effectively, and implement logging strategies.
Understanding Error Types
Operational vs Programming Errors
Type
Description
Examples
Handling
Operational
Runtime problems you can anticipate
Network failures, invalid user input, database down
Handle gracefully, retry, inform user
Programming
Bugs in your code
TypeError, undefined access, wrong API usage
Fix the code, crash and restart
Critical Distinction: Operational errors should be handled. Programming errors should crash the app (in production, use a process manager to restart).
The Error Class
Every error in JavaScript inherits from the built-in Error class. When you create an error, Node.js automatically captures a stack trace — a breadcrumb trail showing exactly which functions were called and in what order leading up to the error. This stack trace is your most valuable debugging tool.
// Built-in Error types -- each signals a different category of problemconst err1 = new Error('Something went wrong'); // Generic errorconst err2 = new TypeError('Expected a string'); // Wrong type usedconst err3 = new RangeError('Value out of range'); // Number outside valid rangeconst err4 = new SyntaxError('Invalid syntax'); // Malformed code or JSON// Error propertiesconsole.log(err1.message); // 'Something went wrong' -- human-readable descriptionconsole.log(err1.name); // 'Error' -- the constructor nameconsole.log(err1.stack); // Stack trace -- shows the call chain that led here
Custom Error Classes
// Base application error -- this is the foundation of a custom error hierarchy.// The key insight: by adding statusCode and isOperational, your error handler// can distinguish "expected" errors (bad user input, missing resource) from// "unexpected" ones (null pointer, out of memory) and respond appropriately.class AppError extends Error { constructor(message, statusCode, isOperational = true) { super(message); this.statusCode = statusCode; // Derive 'fail' (client error, 4xx) vs 'error' (server error, 5xx) this.status = `${statusCode}`.startsWith('4') ? 'fail' : 'error'; // isOperational = true means "we expected this could happen" // isOperational = false means "this is a bug in our code" this.isOperational = isOperational; // Exclude this constructor from the stack trace so the trace // points to where the error was thrown, not where it was constructed Error.captureStackTrace(this, this.constructor); }}// Specific error typesclass NotFoundError extends AppError { constructor(resource = 'Resource') { super(`${resource} not found`, 404); }}class ValidationError extends AppError { constructor(message, errors = []) { super(message, 400); this.errors = errors; }}class UnauthorizedError extends AppError { constructor(message = 'Unauthorized') { super(message, 401); }}class ForbiddenError extends AppError { constructor(message = 'Forbidden') { super(message, 403); }}class ConflictError extends AppError { constructor(message = 'Conflict') { super(message, 409); }}// Usagethrow new NotFoundError('User');throw new ValidationError('Validation failed', [ { field: 'email', message: 'Invalid email format' }]);
// Basic try/catchasync function getData() { try { const response = await fetch('/api/data'); if (!response.ok) { throw new AppError('Failed to fetch data', response.status); } return await response.json(); } catch (error) { if (error.isOperational) { // Handle operational error console.error('Operational error:', error.message); } else { // Re-throw programming errors throw error; } }}// Wrapper function for cleaner code -- eliminates the need for try/catch// in every single route handler. This is a higher-order function: it takes// your async handler, runs it, and if the returned promise rejects,// automatically forwards the error to Express's next().const asyncHandler = (fn) => (req, res, next) => { Promise.resolve(fn(req, res, next)).catch(next);};// Usage in Expressapp.get('/users/:id', asyncHandler(async (req, res) => { const user = await User.findById(req.params.id); if (!user) throw new NotFoundError('User'); res.json(user);}));
Express Error Handling
Centralized Error Handler
// middleware/errorHandler.jsconst errorHandler = (err, req, res, next) => { let error = { ...err }; error.message = err.message; error.stack = err.stack; // Log error console.error('Error:', { message: err.message, stack: err.stack, url: req.originalUrl, method: req.method, ip: req.ip, userId: req.user?.id }); // Mongoose bad ObjectId if (err.name === 'CastError') { error = new AppError('Invalid ID format', 400); } // Mongoose duplicate key if (err.code === 11000) { const field = Object.keys(err.keyValue)[0]; error = new ConflictError(`${field} already exists`); } // Mongoose validation error if (err.name === 'ValidationError') { const errors = Object.values(err.errors).map(e => ({ field: e.path, message: e.message })); error = new ValidationError('Validation failed', errors); } // JWT errors if (err.name === 'JsonWebTokenError') { error = new UnauthorizedError('Invalid token'); } if (err.name === 'TokenExpiredError') { error = new UnauthorizedError('Token expired'); } // Development vs Production responses if (process.env.NODE_ENV === 'development') { res.status(error.statusCode || 500).json({ success: false, error: error.message, stack: error.stack, errors: error.errors }); } else { // Production: Don't leak error details if (error.isOperational) { res.status(error.statusCode).json({ success: false, error: error.message, ...(error.errors && { errors: error.errors }) }); } else { // Programming error: send generic message console.error('UNEXPECTED ERROR:', err); res.status(500).json({ success: false, error: 'Something went wrong' }); } }};module.exports = errorHandler;
404 Handler
// Handle undefined routesapp.use((req, res, next) => { next(new NotFoundError(`Route ${req.originalUrl} not found`));});// Error handler (must be last)app.use(errorHandler);
Global Error Handlers
These are your application’s last line of defense — safety nets that catch errors which slipped through every other handler. In a well-designed app, these should rarely fire. If they fire frequently, you have unhandled errors upstream that need fixing.Think of these like the emergency shutoff on a factory machine: you hope they never activate, but when they do, they prevent catastrophic damage.
// Uncaught exceptions (synchronous code) -- fires when a throw statement// reaches the top of the call stack without being caught.// The process is in an undefined state after this, so exiting is the only safe option.process.on('uncaughtException', (err) => { console.error('UNCAUGHT EXCEPTION! Shutting down...'); console.error(err.name, err.message); console.error(err.stack); process.exit(1); // Let your process manager (PM2, Docker) restart the app});// Unhandled promise rejections -- fires when an async operation rejects// and no .catch() or try/catch is waiting for it.// Starting with Node.js 15+, unhandled rejections crash the process by default.process.on('unhandledRejection', (reason, promise) => { console.error('UNHANDLED REJECTION! Shutting down...'); console.error(reason); // Close server gracefully (finish handling in-flight requests), then exit server.close(() => { process.exit(1); });});// SIGTERM handling -- sent by orchestrators (Heroku, Docker, Kubernetes)// when they want your process to stop. You get a brief window to finish// current work before the process is forcefully killed (SIGKILL).process.on('SIGTERM', () => { console.log('SIGTERM received. Shutting down gracefully'); server.close(() => { console.log('Process terminated'); });});
Production tip: Always run your Node.js process behind a process manager like PM2 or inside a container orchestrator. When process.exit(1) fires, the manager automatically restarts the process, minimizing downtime. Without a process manager, your app just stays dead after a crash.
# Built-in debuggernode inspect app.js# Chrome DevToolsnode --inspect app.js# Then open chrome://inspect in Chrome# Break on first linenode --inspect-brk app.js
console.log is fine during development, but in production you need structured, level-based logging that can write to files, external services, or monitoring platforms. Winston is the most widely used logging library in the Node.js ecosystem. It separates the concept of what you log (levels and messages) from where it goes (transports like console, files, or cloud services).