Error Handling

Error Handling Skill

Consistent error handling patterns for JavaScript applications.

Core Principles

Error Categories

Pattern Quick Reference

Synchronous Errors

// Type guard with assertion
function assertDefined(value, message = 'Value is undefined') {
  if (value === undefined || value === null) {
    throw new Error(message);
  }
  return value;
}

// Defensive programming
function processUser(user) {
  assertDefined(user, 'User is required');
  assertDefined(user.id, 'User ID is required');
  // Safe to use user.id here
}

Asynchronous Errors

// Always handle promise rejections
async function fetchData() {
  try {
    const response = await fetch('/api/data');
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    return await response.json();
  } catch (error) {
    console.error('Fetch failed:', error);
    throw error; // Re-throw for caller to handle
  }
}

Custom Error Classes

// Typed errors with additional context
class ApiError extends Error {
  constructor(status, statusText, body = null) {
    super(`API Error: ${status} ${statusText}`);
    this.name = 'ApiError';
    this.status = status;
    this.body = body;
  }
}

class ValidationError extends Error {
  constructor(field, message) {
    super(`Validation: ${field} - ${message}`);
    this.name = 'ValidationError';
    this.field = field;
  }
}

// Usage
if (error instanceof ApiError && error.status === 401) {
  redirectToLogin();
}

Error Boundaries (Components)

Use the <error-boundary> custom element to catch component errors:

<error-boundary name="user-profile">
  <user-profile user-id="123"></user-profile>
  <template slot="fallback">
    <p>Could not load profile.</p>
  </template>
</error-boundary>

See: /add-error-boundary command for implementation.

Global Error Handlers

// Catch unhandled errors
window.onerror = function(message, source, lineno, colno, error) {
  reportError({
    type: 'uncaught',
    message,
    source,
    line: lineno,
    column: colno,
    stack: error?.stack
  });
  return false; // Allow default handling
};

// Catch unhandled promise rejections
window.onunhandledrejection = function(event) {
  reportError({
    type: 'unhandled-rejection',
    reason: event.reason
  });
};

API Error Responses (Backend)

// Consistent error response format
function errorResponse(res, status, type, message, details = null) {
  res.status(status).json({
    type,
    message,
    ...(details && { details })
  });
}

// Usage in route
app.post('/api/users', (req, res) => {
  const { email, password } = req.body;

  if (!email) {
    return errorResponse(res, 400, 'validation', 'Email is required', {
      field: 'email'
    });
  }

  // ...
});

Error Flow Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  User Action    │────▶│  Error Handler  │────▶│  Error Report   │
│  (click, input) │     │  (try/catch)    │     │  (logging/API)  │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌─────────────────┐
                        │  User Feedback  │
                        │  (toast/inline) │
                        └─────────────────┘

User Feedback Patterns

// Centralized error display
function showError(error, options = {}) {
  const { type = 'toast', duration = 5000 } = options;

  if (type === 'inline' && options.container) {
    options.container.innerHTML = `
      <div class="error-message" role="alert">
        ${error.message}
      </div>
    `;
  } else {
    // Toast notification
    const toast = document.createElement('div');
    toast.className = 'toast toast--error';
    toast.setAttribute('role', 'alert');
    toast.textContent = error.message;
    document.body.appendChild(toast);

    setTimeout(() => toast.remove(), duration);
  }
}

Detailed Implementation

For comprehensive patterns, see these related skills:

Checklist

When implementing error handling:

Frontend

• Global window.onerror handler installed
• Unhandled promise rejections caught
• Error boundaries wrap risky components
• Async functions wrapped with try/catch
• User-friendly error messages shown
• Errors reported to monitoring service

Backend

• Consistent error response format
• Errors logged with context (request ID, user)
• Sensitive data not exposed in errors
• Validation errors return field-level details
• 5xx errors trigger alerts

Both

• Custom error classes for typed handling
• Errors re-thrown after logging (not swallowed)
• Stack traces available in development
• Generic messages in production

Related Skills

• validation - JSON Schema validation with AJV, ValidationError patterns
• observability - Error tracking, performance monitoring
• api-client - Fetch error patterns, retry logic
• javascript-author - Defensive programming, type guards
• nodejs-backend - Server-side error handling
• logging - Structured error logging