📘 Error Handling: Global Error Handler

🎯 Introduction

Welcome to this essential tutorial on global error handling in TypeScript! 🎉 In this guide, we’ll explore how to catch and handle errors gracefully across your entire application.

You’ll discover how global error handlers can transform your backend development experience. Whether you’re building Express APIs 🌐, microservices 🖥️, or complex server applications 📚, understanding error handling is crucial for building robust, maintainable applications.

By the end of this tutorial, you’ll feel confident implementing comprehensive error handling in your TypeScript projects! Let’s dive in! 🏊‍♂️

📚 Understanding Global Error Handling

🤔 What is Global Error Handling?

Global error handling is like having a safety net for your entire application 🕸️. Think of it as a friendly guardian that catches any errors that slip through your normal error handling, ensuring your app doesn’t crash unexpectedly.

In TypeScript terms, a global error handler is a centralized system that catches unhandled errors, processes them consistently, and responds appropriately 🛡️. This means you can:

✨ Prevent application crashes
🚀 Log errors consistently
🛡️ Provide user-friendly error responses
📊 Monitor application health

💡 Why Use Global Error Handling?

Here’s why developers love global error handlers:

Crash Prevention 🔒: Keep your app running even when unexpected errors occur
Consistent Logging 💻: All errors get logged in the same format
Better User Experience 📖: Users see friendly messages instead of stack traces
Debugging Made Easy 🔧: Centralized error information helps you fix issues faster

Real-world example: Imagine building an e-commerce API 🛒. With global error handling, a database connection error won’t crash your entire server - instead, users get a friendly “Please try again later” message while you get detailed logs to fix the issue.

🔧 Basic Syntax and Usage

📝 Simple Express Error Handler

Let’s start with a friendly example:

// 👋 Hello, Express error handling!
import express, { Request, Response, NextFunction } from 'express';

const app = express();

// 🎨 Creating a simple error interface
interface AppError extends Error {
  statusCode?: number;    // 🚨 HTTP status code
  isOperational?: boolean; // 🎯 Is this a known error?
}

// 🛡️ Global error handler middleware
const globalErrorHandler = (
  err: AppError,
  req: Request,
  res: Response,
  next: NextFunction
): void => {
  // 📝 Log the error details
  console.error('🚨 Error caught:', err.message);
  console.error('📍 Stack trace:', err.stack);
  
  // 🎯 Send user-friendly response
  const statusCode = err.statusCode || 500;
  const message = err.isOperational ? err.message : 'Something went wrong! 😰';
  
  res.status(statusCode).json({
    success: false,
    message,
    ...(process.env.NODE_ENV === 'development' && { stack: err.stack })
  });
};

// 🔧 Register the error handler (must be last!)
app.use(globalErrorHandler);

💡 Explanation: Notice how we use a custom AppError interface and provide different responses for development vs production! The error handler must be registered last in Express.

🎯 Common Patterns

Here are patterns you’ll use daily:

// 🏗️ Pattern 1: Custom error classes
class ValidationError extends Error {
  public readonly statusCode = 400;
  public readonly isOperational = true;
  
  constructor(message: string) {
    super(message);
    this.name = 'ValidationError';
  }
}

class DatabaseError extends Error {
  public readonly statusCode = 500;
  public readonly isOperational = true;
  
  constructor(message: string = 'Database operation failed 💾') {
    super(message);
    this.name = 'DatabaseError';
  }
}

// 🎨 Pattern 2: Error factory
const createError = (message: string, statusCode: number = 500): AppError => {
  const error = new Error(message) as AppError;
  error.statusCode = statusCode;
  error.isOperational = true;
  return error;
};

// 🔄 Pattern 3: Async error wrapper
const asyncHandler = (fn: Function) => {
  return (req: Request, res: Response, next: NextFunction) => {
    Promise.resolve(fn(req, res, next)).catch(next);
  };
};

💡 Practical Examples

🛒 Example 1: E-commerce API Error Handler

Let’s build something real:

// 🛍️ Define our error types
interface APIError extends Error {
  statusCode: number;
  isOperational: boolean;
  errorCode?: string; // 🏷️ Custom error codes
}

// 🛒 E-commerce specific errors
class ProductNotFoundError extends Error implements APIError {
  public readonly statusCode = 404;
  public readonly isOperational = true;
  public readonly errorCode = 'PRODUCT_NOT_FOUND';
  
  constructor(productId: string) {
    super(`Product with ID ${productId} not found 🔍`);
    this.name = 'ProductNotFoundError';
  }
}

class InsufficientStockError extends Error implements APIError {
  public readonly statusCode = 400;
  public readonly isOperational = true;
  public readonly errorCode = 'INSUFFICIENT_STOCK';
  
  constructor(available: number, requested: number) {
    super(`Only ${available} items available, but ${requested} requested 📦`);
    this.name = 'InsufficientStockError';
  }
}

// 🎯 Comprehensive error handler
class ErrorHandler {
  // 🚨 Main error handling method
  public static handleError(
    err: APIError,
    req: Request,
    res: Response,
    next: NextFunction
  ): void {
    // 📝 Log error details
    ErrorHandler.logError(err, req);
    
    // 🎨 Format error response
    const errorResponse = ErrorHandler.formatErrorResponse(err);
    
    // 📤 Send response
    res.status(err.statusCode || 500).json(errorResponse);
  }
  
  // 📋 Log error with context
  private static logError(err: APIError, req: Request): void {
    const errorInfo = {
      timestamp: new Date().toISOString(),
      method: req.method,
      url: req.url,
      userAgent: req.get('User-Agent'),
      ip: req.ip,
      error: {
        name: err.name,
        message: err.message,
        stack: err.stack,
        statusCode: err.statusCode,
        errorCode: err.errorCode
      }
    };
    
    // 🔍 Different log levels based on error severity
    if (err.statusCode >= 500) {
      console.error('🚨 CRITICAL ERROR:', JSON.stringify(errorInfo, null, 2));
    } else {
      console.warn('⚠️ CLIENT ERROR:', JSON.stringify(errorInfo, null, 2));
    }
  }
  
  // 🎨 Format consistent error responses
  private static formatErrorResponse(err: APIError) {
    const isProduction = process.env.NODE_ENV === 'production';
    
    return {
      success: false,
      error: {
        message: err.isOperational ? err.message : 'Internal server error 😰',
        code: err.errorCode || 'UNKNOWN_ERROR',
        statusCode: err.statusCode || 500,
        timestamp: new Date().toISOString(),
        // 🔧 Include stack trace only in development
        ...((!isProduction && err.stack) && { stack: err.stack })
      }
    };
  }
}

// 🎮 Let's use it in routes!
app.get('/products/:id', asyncHandler(async (req: Request, res: Response) => {
  const { id } = req.params;
  
  // 🔍 Simulate product lookup
  const product = await findProductById(id);
  if (!product) {
    throw new ProductNotFoundError(id);
  }
  
  res.json({ success: true, data: product });
}));

app.post('/cart/add', asyncHandler(async (req: Request, res: Response) => {
  const { productId, quantity } = req.body;
  
  // 📦 Check stock availability
  const stock = await getProductStock(productId);
  if (stock < quantity) {
    throw new InsufficientStockError(stock, quantity);
  }
  
  // ✅ Add to cart logic here
  res.json({ success: true, message: 'Item added to cart! 🛒' });
}));

// 🛡️ Register our error handler
app.use(ErrorHandler.handleError);

🎯 Try it yourself: Add a PaymentFailedError class and handle credit card processing failures!

🎮 Example 2: Game Server Error Handling

Let’s make error handling fun:

// 🏆 Game-specific error types
enum GameErrorCode {
  PLAYER_NOT_FOUND = 'PLAYER_NOT_FOUND',
  GAME_FULL = 'GAME_FULL',
  INVALID_MOVE = 'INVALID_MOVE',
  GAME_OVER = 'GAME_OVER',
  CONNECTION_LOST = 'CONNECTION_LOST'
}

interface GameError extends Error {
  code: GameErrorCode;
  playerId?: string;
  gameId?: string;
  severity: 'low' | 'medium' | 'high' | 'critical';
}

class GameErrorHandler {
  // 🎮 Handle game-specific errors
  public static handleGameError(error: GameError): void {
    // 📊 Log based on severity
    switch (error.severity) {
      case 'critical':
        console.error('🚨 CRITICAL GAME ERROR:', {
          code: error.code,
          message: error.message,
          playerId: error.playerId,
          gameId: error.gameId,
          timestamp: new Date().toISOString()
        });
        // 📧 Could send alerts to development team
        break;
        
      case 'high':
        console.error('🔴 HIGH PRIORITY:', error.message);
        break;
        
      case 'medium':
        console.warn('🟡 MEDIUM PRIORITY:', error.message);
        break;
        
      case 'low':
        console.info('🟢 LOW PRIORITY:', error.message);
        break;
    }
    
    // 🎯 Take appropriate action
    GameErrorHandler.handleErrorAction(error);
  }
  
  // 🎪 Different actions based on error type
  private static handleErrorAction(error: GameError): void {
    switch (error.code) {
      case GameErrorCode.CONNECTION_LOST:
        // 🔄 Attempt reconnection
        console.log('🔄 Attempting to reconnect player...');
        break;
        
      case GameErrorCode.GAME_FULL:
        // 📋 Add to waiting list
        console.log('📋 Adding player to waiting list...');
        break;
        
      case GameErrorCode.INVALID_MOVE:
        // ⚠️ Notify player
        console.log('⚠️ Notifying player of invalid move...');
        break;
        
      default:
        console.log('🤔 Handling generic error...');
    }
  }
}

// 🎮 Example usage in game server
const processPlayerMove = (playerId: string, move: any): void => {
  try {
    // 🎯 Game logic here
    validateMove(move);
    applyMove(playerId, move);
  } catch (error) {
    const gameError: GameError = {
      name: 'InvalidMoveError',
      message: `Invalid move by player ${playerId} 🎮`,
      code: GameErrorCode.INVALID_MOVE,
      playerId,
      severity: 'medium'
    };
    
    GameErrorHandler.handleGameError(gameError);
  }
};

🚀 Advanced Concepts

🧙‍♂️ Advanced Topic 1: Error Recovery Strategies

When you’re ready to level up, try this advanced pattern:

// 🎯 Advanced error recovery system
interface RecoveryStrategy {
  canRecover(error: Error): boolean;
  recover(error: Error, context: any): Promise<any>;
  fallback(error: Error, context: any): any;
}

class DatabaseRecoveryStrategy implements RecoveryStrategy {
  private retryAttempts = 3;
  private retryDelay = 1000; // 🕐 1 second
  
  canRecover(error: Error): boolean {
    // 🔍 Check if it's a recoverable database error
    return error.message.includes('connection') || 
           error.message.includes('timeout');
  }
  
  async recover(error: Error, context: any): Promise<any> {
    console.log('🔄 Attempting database recovery...');
    
    for (let attempt = 1; attempt <= this.retryAttempts; attempt++) {
      try {
        // ⏳ Wait before retry
        await new Promise(resolve => setTimeout(resolve, this.retryDelay * attempt));
        
        // 🔄 Retry the operation
        return await context.operation();
      } catch (retryError) {
        console.log(`💥 Retry attempt ${attempt} failed`);
        if (attempt === this.retryAttempts) {
          throw retryError;
        }
      }
    }
  }
  
  fallback(error: Error, context: any): any {
    // 📋 Return cached data or default response
    console.log('📋 Using fallback strategy...');
    return { success: false, message: 'Service temporarily unavailable 🚧' };
  }
}

// 🪄 Error recovery manager
class ErrorRecoveryManager {
  private strategies: RecoveryStrategy[] = [];
  
  addStrategy(strategy: RecoveryStrategy): void {
    this.strategies.push(strategy);
  }
  
  async handleErrorWithRecovery(error: Error, context: any): Promise<any> {
    // 🔍 Find a strategy that can handle this error
    const strategy = this.strategies.find(s => s.canRecover(error));
    
    if (strategy) {
      try {
        console.log('✨ Attempting error recovery...');
        return await strategy.recover(error, context);
      } catch (recoveryError) {
        console.log('🚫 Recovery failed, using fallback...');
        return strategy.fallback(error, context);
      }
    }
    
    // 💥 No recovery strategy available
    throw error;
  }
}

🏗️ Advanced Topic 2: Error Monitoring Integration

For the brave developers:

// 🚀 Integration with monitoring services
interface ErrorMonitor {
  reportError(error: Error, context: ErrorContext): void;
  reportMetric(metric: string, value: number): void;
}

interface ErrorContext {
  userId?: string;
  requestId?: string;
  environment: string;
  timestamp: Date;
  metadata?: Record<string, any>;
}

class ProductionErrorMonitor implements ErrorMonitor {
  reportError(error: Error, context: ErrorContext): void {
    // 📊 Send to external monitoring service (like Sentry)
    const errorReport = {
      message: error.message,
      stack: error.stack,
      level: this.getErrorLevel(error),
      user: { id: context.userId },
      request: { id: context.requestId },
      environment: context.environment,
      timestamp: context.timestamp.toISOString(),
      extra: context.metadata
    };
    
    // 🚀 This would integrate with your monitoring service
    console.log('📊 Reporting to monitoring service:', errorReport);
  }
  
  reportMetric(metric: string, value: number): void {
    // 📈 Track error metrics
    console.log(`📈 Metric: ${metric} = ${value}`);
  }
  
  private getErrorLevel(error: Error): string {
    if (error.name.includes('Critical')) return 'error';
    if (error.name.includes('Warning')) return 'warning';
    return 'info';
  }
}

⚠️ Common Pitfalls and Solutions

😱 Pitfall 1: Swallowing Errors

// ❌ Wrong way - hiding errors!
const handleRequest = async (req: Request, res: Response) => {
  try {
    const data = await someAsyncOperation();
    res.json(data);
  } catch (error) {
    // 💥 Silent failure - user never knows what happened!
    res.json({ success: false });
  }
};

// ✅ Correct way - proper error handling!
const handleRequest = async (req: Request, res: Response, next: NextFunction) => {
  try {
    const data = await someAsyncOperation();
    res.json({ success: true, data });
  } catch (error) {
    // 🎯 Pass to global error handler
    next(error);
  }
};

🤯 Pitfall 2: Exposing Sensitive Information

// ❌ Dangerous - exposing internal details!
const errorHandler = (err: Error, req: Request, res: Response) => {
  res.status(500).json({
    error: err.message,
    stack: err.stack, // 💥 Exposes internal structure!
    query: req.query  // 💥 Might contain sensitive data!
  });
};

// ✅ Safe - sanitized error responses!
const errorHandler = (err: Error, req: Request, res: Response) => {
  const isProduction = process.env.NODE_ENV === 'production';
  
  res.status(500).json({
    success: false,
    message: isProduction ? 'Internal server error' : err.message,
    // 🛡️ Only include debug info in development
    ...((!isProduction) && { 
      stack: err.stack,
      timestamp: new Date().toISOString()
    })
  });
};

🛠️ Best Practices

🎯 Be Specific: Create custom error classes for different scenarios
📝 Log Everything: Include context like user ID, request ID, timestamp
🛡️ Sanitize Responses: Never expose sensitive data in error messages
🎨 Use Error Codes: Implement consistent error codes for client handling
✨ Plan Recovery: Always have fallback strategies for critical operations
📊 Monitor Metrics: Track error rates and patterns
🔄 Test Error Paths: Write tests for your error handling code

🧪 Hands-On Exercise

🎯 Challenge: Build a Robust API Error System

Create a comprehensive error handling system for a social media API:

📋 Requirements:

✅ Custom error classes for different scenarios (UserNotFound, PostNotFound, etc.)
🏷️ Error codes and severity levels
👤 Context tracking (user ID, request ID)
📅 Rate limiting error handling
🎨 Different responses for different client types (web vs mobile)
📊 Error metrics and monitoring

🚀 Bonus Points:

Add error recovery for database failures
Implement circuit breaker pattern
Create error notification system
Add error correlation across microservices

💡 Solution

🔍 Click to see solution

// 🎯 Our comprehensive error handling system!

// 📋 Base error interface
interface APIError extends Error {
  statusCode: number;
  errorCode: string;
  severity: 'low' | 'medium' | 'high' | 'critical';
  isOperational: boolean;
  context?: Record<string, any>;
}

// 🏗️ Custom error classes
class UserNotFoundError extends Error implements APIError {
  public readonly statusCode = 404;
  public readonly errorCode = 'USER_NOT_FOUND';
  public readonly severity = 'medium' as const;
  public readonly isOperational = true;
  
  constructor(userId: string, context?: Record<string, any>) {
    super(`User with ID ${userId} not found 👤`);
    this.name = 'UserNotFoundError';
    this.context = context;
  }
}

class RateLimitExceededError extends Error implements APIError {
  public readonly statusCode = 429;
  public readonly errorCode = 'RATE_LIMIT_EXCEEDED';
  public readonly severity = 'low' as const;
  public readonly isOperational = true;
  
  constructor(limit: number, resetTime: Date) {
    super(`Rate limit exceeded. Limit: ${limit}/hour. Resets at: ${resetTime.toISOString()} ⏰`);
    this.name = 'RateLimitExceededError';
  }
}

class DatabaseConnectionError extends Error implements APIError {
  public readonly statusCode = 503;
  public readonly errorCode = 'DATABASE_UNAVAILABLE';
  public readonly severity = 'critical' as const;
  public readonly isOperational = true;
  
  constructor(operation: string) {
    super(`Database connection failed during ${operation} 💾`);
    this.name = 'DatabaseConnectionError';
  }
}

// 🎨 Error response formatter
class ErrorResponseFormatter {
  static formatForClient(error: APIError, clientType: 'web' | 'mobile', isDev: boolean) {
    const baseResponse = {
      success: false,
      error: {
        code: error.errorCode,
        message: this.getUserFriendlyMessage(error, clientType),
        timestamp: new Date().toISOString()
      }
    };
    
    // 🔧 Add debug info in development
    if (isDev) {
      return {
        ...baseResponse,
        debug: {
          originalMessage: error.message,
          stack: error.stack,
          context: error.context
        }
      };
    }
    
    return baseResponse;
  }
  
  private static getUserFriendlyMessage(error: APIError, clientType: 'web' | 'mobile'): string {
    const messages = {
      web: {
        USER_NOT_FOUND: 'The requested user could not be found. Please check the user ID and try again.',
        RATE_LIMIT_EXCEEDED: 'Too many requests. Please wait a moment before trying again.',
        DATABASE_UNAVAILABLE: 'Our service is temporarily unavailable. Please try again in a few minutes.'
      },
      mobile: {
        USER_NOT_FOUND: 'User not found 👤',
        RATE_LIMIT_EXCEEDED: 'Too many requests ⏰',
        DATABASE_UNAVAILABLE: 'Service unavailable 🚧'
      }
    };
    
    return messages[clientType][error.errorCode as keyof typeof messages.web] || 
           'An unexpected error occurred. Please try again.';
  }
}

// 📊 Error metrics tracker
class ErrorMetrics {
  private static errorCounts = new Map<string, number>();
  private static lastReset = new Date();
  
  static trackError(error: APIError): void {
    const key = `${error.errorCode}_${error.severity}`;
    const current = this.errorCounts.get(key) || 0;
    this.errorCounts.set(key, current + 1);
    
    // 🚨 Alert on critical errors
    if (error.severity === 'critical') {
      this.alertCriticalError(error);
    }
    
    // 📈 Log metrics every hour
    this.maybeLogMetrics();
  }
  
  private static alertCriticalError(error: APIError): void {
    console.error('🚨 CRITICAL ERROR ALERT:', {
      code: error.errorCode,
      message: error.message,
      context: error.context,
      timestamp: new Date().toISOString()
    });
    
    // 📧 Here you would send alerts to your team
  }
  
  private static maybeLogMetrics(): void {
    const now = new Date();
    const hoursSinceReset = (now.getTime() - this.lastReset.getTime()) / (1000 * 60 * 60);
    
    if (hoursSinceReset >= 1) {
      console.log('📊 Hourly Error Metrics:', Object.fromEntries(this.errorCounts));
      this.errorCounts.clear();
      this.lastReset = now;
    }
  }
}

// 🛡️ Main error handler
class SocialMediaErrorHandler {
  static handleError(
    err: APIError,
    req: Request,
    res: Response,
    next: NextFunction
  ): void {
    // 📊 Track the error
    ErrorMetrics.trackError(err);
    
    // 📝 Log with context
    this.logError(err, req);
    
    // 🎯 Get client type from headers
    const clientType = req.headers['x-client-type'] === 'mobile' ? 'mobile' : 'web';
    const isDev = process.env.NODE_ENV === 'development';
    
    // 🎨 Format response
    const response = ErrorResponseFormatter.formatForClient(err, clientType, isDev);
    
    // 📤 Send response
    res.status(err.statusCode).json(response);
  }
  
  private static logError(err: APIError, req: Request): void {
    const logData = {
      timestamp: new Date().toISOString(),
      severity: err.severity,
      errorCode: err.errorCode,
      message: err.message,
      request: {
        method: req.method,
        url: req.url,
        userAgent: req.get('User-Agent'),
        ip: req.ip,
        userId: req.headers['x-user-id']
      },
      context: err.context
    };
    
    // 📋 Log based on severity
    switch (err.severity) {
      case 'critical':
        console.error('🚨 CRITICAL:', JSON.stringify(logData, null, 2));
        break;
      case 'high':
        console.error('🔴 HIGH:', JSON.stringify(logData, null, 2));
        break;
      case 'medium':
        console.warn('🟡 MEDIUM:', JSON.stringify(logData, null, 2));
        break;
      case 'low':
        console.info('🟢 LOW:', JSON.stringify(logData, null, 2));
        break;
    }
  }
}

// 🎮 Example usage
app.get('/users/:id', async (req: Request, res: Response, next: NextFunction) => {
  try {
    const user = await findUserById(req.params.id);
    if (!user) {
      throw new UserNotFoundError(req.params.id, { 
        requestId: req.headers['x-request-id'],
        userAgent: req.get('User-Agent')
      });
    }
    
    res.json({ success: true, data: user });
  } catch (error) {
    next(error);
  }
});

// 🛡️ Register the error handler
app.use(SocialMediaErrorHandler.handleError);

🎓 Key Takeaways

You’ve learned so much! Here’s what you can now do:

✅ Create global error handlers with confidence 💪
✅ Avoid common mistakes that crash applications 🛡️
✅ Apply best practices in real projects 🎯
✅ Debug issues like a pro 🐛
✅ Build resilient backends with TypeScript! 🚀

Remember: Error handling isn’t just about catching errors - it’s about creating great user experiences even when things go wrong! 🤝

🤝 Next Steps

Congratulations! 🎉 You’ve mastered global error handling in TypeScript!

Here’s what to do next:

💻 Practice with the exercises above
🏗️ Build a project with comprehensive error handling
📚 Move on to our next tutorial: “Logging: Structured Logging with Winston”
🌟 Share your error handling strategies with others!

Remember: Every backend expert was once a beginner. Keep coding, keep learning, and most importantly, handle those errors gracefully! 🚀

Happy coding! 🎉🚀✨

Prerequisites

What you'll learn