Error Handling - Exception & Logging Patterns

Production patterns for error handling, boundaries, structured logging, and recovery

When to Use This Skill

Use this skill when:

• Implementing try-catch error handling

• Building React error boundaries

• Setting up structured logging

• Designing API error responses

• Handling async/Promise errors

• Creating custom error classes

• Implementing graceful degradation

Don't use this skill when:

• Building happy path only (always handle errors!)

• Using framework-specific patterns (check stack skills first)

Critical Patterns

Pattern 1: Custom Error Classes

When: Creating typed, structured errors

// ✅ GOOD: Hierarchical error classes // src/errors/base.ts export class AppError extends Error { public readonly isOperational: boolean; public readonly statusCode: number; public readonly code: string;

constructor( message: string, statusCode: number = 500, code: string = 'INTERNAL_ERROR', isOperational: boolean = true ) { super(message); this.name = this.constructor.name; this.statusCode = statusCode; this.code = code; this.isOperational = isOperational;

Error.captureStackTrace(this, this.constructor);

} }

// Specific error types export class NotFoundError extends AppError { constructor(resource: string = 'Resource') { super(${resource} not found, 404, 'NOT_FOUND'); } }

export class ValidationError extends AppError { constructor( message: string, public readonly details?: Record<string, string[]> ) { super(message, 400, 'VALIDATION_ERROR'); } }

export class UnauthorizedError extends AppError { constructor(message: string = 'Unauthorized') { super(message, 401, 'UNAUTHORIZED'); } }

export class ConflictError extends AppError { constructor(message: string = 'Resource already exists') { super(message, 409, 'CONFLICT'); } }

// ❌ BAD: Throwing plain strings or generic errors throw 'Something went wrong'; // No type, no stack trace throw new Error('Not found'); // No status code, no classification

Pattern 2: Async Error Handling

When: Handling errors in async operations

// ✅ GOOD: Centralized async error wrapper type AsyncFunction<T> = (...args: any[]) => Promise<T>;

function handleAsync<T>(fn: AsyncFunction<T>) { return async (...args: any[]): Promise<T> => { try { return await fn(...args); } catch (error) { // Log the error logger.error('Async operation failed', { error, args });

  // Re-throw operational errors
  if (error instanceof AppError && error.isOperational) {
    throw error;
  }

  // Wrap unknown errors
  throw new AppError('An unexpected error occurred', 500, 'INTERNAL_ERROR', false);
}

}; }

// Usage const createUser = handleAsync(async (data: CreateUserInput) => { const existing = await db.user.findUnique({ where: { email: data.email } }); if (existing) { throw new ConflictError('Email already registered'); } return db.user.create({ data }); });

// ✅ GOOD: Promise.allSettled for parallel operations async function processItems(items: Item[]) { const results = await Promise.allSettled( items.map(item => processItem(item)) );

const successful = results .filter((r): r is PromiseFulfilledResult<Item> => r.status === 'fulfilled') .map(r => r.value);

const failed = results .filter((r): r is PromiseRejectedResult => r.status === 'rejected') .map(r => r.reason);

if (failed.length > 0) { logger.warn(${failed.length} items failed to process, { failed }); }

return { successful, failed }; }

// ❌ BAD: Unhandled promise rejection async function riskyOperation() { const data = await fetchData(); // If this throws, app crashes! return data; }

Pattern 3: React Error Boundaries

When: Catching render errors in React

// ✅ GOOD: Error boundary component "use client";

import { Component, ReactNode } from 'react';

interface Props { children: ReactNode; fallback?: ReactNode; onError?: (error: Error, errorInfo: React.ErrorInfo) => void; }

interface State { hasError: boolean; error: Error | null; }

export class ErrorBoundary extends Component<Props, State> { constructor(props: Props) { super(props); this.state = { hasError: false, error: null }; }

static getDerivedStateFromError(error: Error): State { return { hasError: true, error }; }

componentDidCatch(error: Error, errorInfo: React.ErrorInfo) { // Log to error reporting service console.error('Error boundary caught:', error, errorInfo); this.props.onError?.(error, errorInfo); }

render() { if (this.state.hasError) { return this.props.fallback || ( <div className="p-4 border border-red-500 rounded"> <h2>Something went wrong</h2> <button onClick={() => this.setState({ hasError: false, error: null })}> Try again </button> </div> ); }

return this.props.children;

} }

// Usage <ErrorBoundary fallback={<ErrorFallback />} onError={(error) => reportToSentry(error)}

<Dashboard /> </ErrorBoundary>

// ❌ BAD: No error boundary (entire app crashes on render error) function App() { return <Dashboard />; // If Dashboard throws, white screen! }

Pattern 4: Structured Logging

When: Creating queryable, parseable logs

// ✅ GOOD: Structured logger with context import pino from 'pino';

const logger = pino({ level: process.env.LOG_LEVEL || 'info', formatters: { level: (label) => ({ level: label }), }, base: { service: process.env.SERVICE_NAME, environment: process.env.NODE_ENV, }, });

// Create child logger with request context function createRequestLogger(req: Request) { return logger.child({ requestId: req.headers.get('x-request-id'), path: new URL(req.url).pathname, method: req.method, }); }

// Usage app.use((req, res, next) => { req.log = createRequestLogger(req); req.log.info('Request started');

res.on('finish', () => { req.log.info('Request completed', { statusCode: res.statusCode, duration: Date.now() - req.startTime, }); });

next(); });

// In handlers async function getUser(req, res) { req.log.info('Fetching user', { userId: req.params.id });

try { const user = await userService.findById(req.params.id); req.log.info('User found', { userId: user.id }); res.json(user); } catch (error) { req.log.error('Failed to fetch user', { userId: req.params.id, error: error.message, stack: error.stack, }); throw error; } }

// ❌ BAD: Console.log with no structure console.log('User not found: ' + userId); // Can't query, no context console.log(error); // Object might not serialize properly

Pattern 5: Graceful Degradation

When: Maintaining functionality when components fail

// ✅ GOOD: Fallback values and graceful degradation async function getDashboardData(userId: string) { const [userResult, statsResult, recentResult] = await Promise.allSettled([ getUserProfile(userId), getAnalyticsStats(userId), getRecentActivity(userId), ]);

return { user: userResult.status === 'fulfilled' ? userResult.value : { name: 'Unknown', error: true },

stats: statsResult.status === 'fulfilled'
  ? statsResult.value
  : { error: true, message: 'Stats unavailable' },

recent: recentResult.status === 'fulfilled'
  ? recentResult.value
  : [],

}; }

// ✅ GOOD: Circuit breaker pattern class CircuitBreaker { private failures = 0; private lastFailure: number = 0; private state: 'closed' | 'open' | 'half-open' = 'closed';

constructor( private threshold: number = 5, private timeout: number = 30000 ) {}

async execute<T>(fn: () => Promise<T>): Promise<T> { if (this.state === 'open') { if (Date.now() - this.lastFailure > this.timeout) { this.state = 'half-open'; } else { throw new Error('Circuit breaker is open'); } }

try {
  const result = await fn();
  this.onSuccess();
  return result;
} catch (error) {
  this.onFailure();
  throw error;
}

}

private onSuccess() { this.failures = 0; this.state = 'closed'; }

private onFailure() { this.failures++; this.lastFailure = Date.now(); if (this.failures >= this.threshold) { this.state = 'open'; } } }

// ❌ BAD: All or nothing approach async function getDashboard(userId: string) { const user = await getUserProfile(userId); // If this fails, entire dashboard fails const stats = await getStats(userId); const recent = await getRecent(userId); return { user, stats, recent }; }

Code Examples

For complete, production-ready examples, see references/examples.md:

• API Error Handler Middleware

• React Query Error Handling

• Error Reporting Integration (Sentry)

• Error Boundary with Recovery

Anti-Patterns

Don't: Swallow Errors Silently

// ❌ BAD: Silent error swallowing try { await riskyOperation(); } catch (error) { // Nothing happens - bug is hidden! }

// ✅ GOOD: At minimum, log the error try { await riskyOperation(); } catch (error) { logger.error('Operation failed', { error }); // Decide: rethrow, return fallback, or handle }

Don't: Expose Internal Details

// ❌ BAD: Leaking implementation details res.status(500).json({ error: error.message, // "Cannot read property 'x' of undefined" stack: error.stack, // Full stack trace! });

// ✅ GOOD: Safe error response res.status(500).json({ error: 'An unexpected error occurred', requestId: req.id, // For support lookup });

Don't: Use Generic Catch-All

// ❌ BAD: Catching everything the same way try { await processPayment(); } catch (error) { return { error: 'Failed' }; // Lost all context! }

// ✅ GOOD: Handle specific errors differently try { await processPayment(); } catch (error) { if (error instanceof PaymentDeclinedError) { return { error: 'Payment declined', code: 'DECLINED' }; } if (error instanceof NetworkError) { return { error: 'Please try again', code: 'NETWORK' }; } throw error; // Unknown error - let it bubble up }

Quick Reference

Scenario Pattern Example

HTTP errors Custom error classes throw new NotFoundError()

Async errors try-catch + wrapper handleAsync(fn)

React errors Error boundary <ErrorBoundary>

Parallel failures Promise.allSettled Promise.allSettled([...])

Logging Structured logger logger.error('msg', { context })

External service Circuit breaker breaker.execute(fn)

Resources

Related Skills:

• observability: Monitoring and tracing

• security: Secure error messages

• api-design: Error response formats

Keywords

error-handling , exceptions , try-catch , error-boundary , logging , structured-logging , graceful-degradation , circuit-breaker , pino , sentry