Error Handling

Why This Skill Exists

Inconsistent error handling leads to swallowed errors, unhelpful messages, and debugging nightmares. These patterns ensure errors are caught at the right level, logged with context, and surfaced appropriately.

Core Principles

1. Fail Fast, Fail Loud

Detect errors at the earliest possible point. Don't let invalid state propagate.

// Bad — silent corruption
function processOrder(order: Order) {
  const total = order.items?.reduce((sum, i) => sum + i.price, 0) ?? 0
  // continues with total=0 if items is undefined — wrong!
}

// Good — fail fast
function processOrder(order: Order) {
  if (!order.items?.length) {
    throw new ValidationError('Order must have at least one item')
  }
  const total = order.items.reduce((sum, i) => sum + i.price, 0)
}

2. User Errors vs System Errors

warn

info

info

warn

error

error

3. Error Context — The Debugging Lifeline

Always include context when logging errors:

// Bad — no context
logger.error('Failed to process payment')

// Good — actionable context
logger.error('Failed to process payment', {
  orderId: order.id,
  userId: order.userId,
  amount: order.total,
  provider: 'stripe',
  stripeError: err.code,
  attempt: retryCount,
})

4. Error Boundaries

Catch errors at architectural boundaries, not everywhere:

Controller (catch → HTTP response)
  └── Service (catch → rethrow with context)
       └── Repository (catch → wrap DB errors)
            └── Database driver (throws raw errors)

Don't catch errors in the middle just to log and rethrow — that creates duplicate log entries.

5. Custom Error Classes

class AppError extends Error {
  constructor(
    message: string,
    public code: string,
    public statusCode: number = 500,
    public isOperational: boolean = true,
  ) {
    super(message)
    this.name = this.constructor.name
  }
}

class ValidationError extends AppError {
  constructor(message: string) {
    super(message, 'VALIDATION_FAILED', 400)
  }
}

class NotFoundError extends AppError {
  constructor(resource: string, id: string) {
    super(`${resource} not found: ${id}`, 'NOT_FOUND', 404)
  }
}

6. Never Swallow Errors

// NEVER do this
try { riskyOperation() } catch (e) { /* ignore */ }

// If you genuinely want to ignore, explain WHY
try {
  await analytics.track(event)
} catch {
  // Analytics failure is non-critical — don't break the user flow
}

Anti-Patterns

catch (e) {}

catch (e) { throw e }

catch (e) { log(e); throw e }

throw "failed"