claude-workspace: Skill for Claude Code

Error Handling

The Error Handling Hierarchy

Errors should be caught at the closest meaningful boundary, not at the top of the tree.

App Error Boundary (crash recovery, "something went wrong" page)
  └─ Route Error Boundary (per-page, Next.js error.tsx)
       └─ Feature Error Boundary (per-feature section)
            └─ Component-level try/catch (inline error UI)
                 └─ Query/Mutation onError (toast notifications)

Custom Error Classes

// lib/errors.ts
export class AppError extends Error {
  constructor(
    message: string,
    public code: string,
    public statusCode: number = 500,
    public isOperational: boolean = true,  // Expected vs unexpected
    public context?: Record<string, unknown>,
  ) {
    super(message);
    this.name = 'AppError';
  }
}

export class ValidationError extends AppError {
  constructor(message: string, public fields: Record<string, string[]>) {
    super(message, 'VALIDATION_ERROR', 400);
    this.name = 'ValidationError';
  }
}

export class AuthError extends AppError {
  constructor(message = 'Authentication required') {
    super(message, 'AUTH_ERROR', 401);
    this.name = 'AuthError';
  }
}

export class NotFoundError extends AppError {
  constructor(resource: string, id: string) {
    super(`${resource} not found: ${id}`, 'NOT_FOUND', 404);
    this.name = 'NotFoundError';
  }
}

Error Normalizer

// lib/errors/normalize.ts
import { AppError } from './errors';

export function normalizeError(error: unknown): AppError {
  // Already normalized
  if (error instanceof AppError) return error;

  // API errors
  if (error instanceof Response || (error && typeof error === 'object' && 'status' in error)) {
    const e = error as { status: number; statusText?: string };
    return new AppError(
      e.statusText ?? 'Request failed',
      'API_ERROR',
      e.status,
    );
  }

  // Network errors
  if (error instanceof TypeError && error.message.includes('fetch')) {
    return new AppError('Network error — check your connection', 'NETWORK_ERROR', 0);
  }

  // Abort errors (not real errors)
  if (error instanceof DOMException && error.name === 'AbortError') {
    return new AppError('Request cancelled', 'ABORT_ERROR', 0, true);
  }

  // Unknown errors
  const message = error instanceof Error ? error.message : 'An unexpected error occurred';
  return new AppError(message, 'UNKNOWN_ERROR', 500, false);
}