Error Handling in JavaScript: Try, Catch, Finally

r(message); this.name = this.constructor.name; // Ensures stack traces exclude the constructor wrapper Error.captureStackTrace(this, this.constructor); } }

class DataParsingError extends BaseRuntimeError { constructor(message: string, public readonly rawPayload: unknown) { super('DATA_PARSE_FAILURE', message, true); } }

class ExternalServiceError extends BaseRuntimeError { constructor(message: string, public readonly statusCode: number) { super('EXTERNAL_SERVICE_DOWN', message, true); } }

**Architecture Rationale**: 
- `isOperational` flags distinguish recoverable failures from code defects. Operational errors trigger retries or fallbacks; non-operational errors trigger crash reporting.
- `Error.captureStackTrace` prevents the base class constructor from polluting the stack trace, preserving accurate file/line references.
- Discriminated properties (`rawPayload`, `statusCode`) attach context directly to the error object, eliminating the need for global state or closure variables during recovery.

### Step 2: Implement a Centralized Error Router

Instead of scattering recovery logic across components, route all caught errors through a single dispatcher. This enforces consistent logging, metrics emission, and user feedback.

```typescript
type ErrorRecoveryAction = 'RETRY' | 'FALLBACK' | 'ABORT' | 'LOG_ONLY';

function routeFailure(error: unknown): ErrorRecoveryAction {
  if (error instanceof DataParsingError) {
    console.warn(`[Parser] ${error.errorCode}: ${error.message}`);
    // Emit to analytics pipeline
    return 'FALLBACK';
  }

  if (error instanceof ExternalServiceError) {
    console.error(`[Network] ${error.errorCode} (${error.statusCode})`);
    // Queue for exponential backoff retry
    return error.statusCode >= 500 ? 'RETRY' : 'ABORT';
  }

  // Fallback for untyped or unexpected errors
  console.error('[System] Unhandled failure:', error);
  return 'LOG_ONLY';
}

Architecture Rationale:

• Returning an action enum decouples error detection from error resolution. The calling function decides how to apply the action based on its specific context.
• Centralization ensures observability tools receive uniform payloads, simplifying dashboard configuration and alert routing.

Step 3: Wrap Risky Operations with Deterministic Boundaries

Apply try/catch/finally at logical execution boundaries, not arbitrary line breaks. Use finally exclusively for resource cleanup, never for control flow.

interface TransactionContext {
  connectionId: string;
  release: () => Promise<void>;
}

async function executePaymentOperation(
  payload: Record<string, unknown>,
  acquireConnection: () => Promise<TransactionContext>
): Promise<{ success: boolean; data?: unknown }> {
  let activeConnection: TransactionContext | null = null;

  try {
    activeConnection = await acquireConnection();
    
    // Simulate risky external call
    const response = await fetch('/api/v1/process-payment', {
      method: 'POST',
      body: JSON.stringify(payload),
    });

    if (!response.ok) {
      throw new ExternalServiceError('Payment gateway rejected request', response.status);
    }

    const result = await response.json();
    return { success: true, data: result };
  } catch (err) {
    const action = routeFailure(err);
    
    if (action === 'FALLBACK') {
      return { success: false, data: { fallback: true } };
    }
    if (action === 'ABORT') {
      throw err; // Re-throw to bubble up to UI boundary
    }
    
    return { success: false };
  } finally {
    // Guaranteed cleanup regardless of success, error, or early return
    if (activeConnection) {
      await activeConnection.release();
    }
  }
}

Architecture Rationale:

• The try block contains only the minimal risky operations. This prevents masking unrelated bugs.
• finally executes after try or catch, even if they contain return or throw statements. This guarantees connection release, preventing resource leaks under failure conditions.
• Re-throwing non-recoverable errors preserves the call stack for upstream boundaries (e.g., React error boundaries or Express middleware).

Pitfall Guide

1. Silent Error Swallowing

Explanation: Catch blocks that contain no logging, metrics emission, or re-throwing effectively hide failures. Downstream code receives undefined or partial state, causing cascading bugs that are exponentially harder to trace. Fix: Every catch must either log the error, emit a metric, return a typed fallback, or re-throw. Never leave a catch block empty.

2. Attempting to Catch Syntax Errors at Runtime

Explanation: SyntaxError occurs during the parsing phase before execution begins. try/catch operates at runtime and cannot intercept parse failures. Fix: Rely on static analysis tools (TypeScript, ESLint, Babel) to catch syntax issues during development. Runtime error handling should focus on TypeError, ReferenceError, RangeError, and custom operational errors.

3. Over-Nesting Try/Catch Blocks

Explanation: Wrapping every statement in its own try/catch fragments the execution flow, obscures the actual failure point, and degrades performance due to repeated stack unwinding. Fix: Group related operations into logical units. Wrap at the boundary of a feature or service call. Let internal failures propagate to the boundary where context is available for recovery.

4. Ignoring Async Rejection Mechanics

Explanation: await unwraps promises, but if the promise rejects and isn't caught, it throws synchronously in the async function. Forgetting to wrap await calls in try/catch leaves rejections unhandled. Fix: Always pair await with try/catch when the rejection is expected. For fire-and-forget promises, attach .catch() explicitly or use Promise.allSettled() for batch operations.

5. Mutating Caught Error Objects

Explanation: Developers often attach properties to caught errors (err.retryCount = 1) to pass state through the catch block. This mutates the original error instance, which can corrupt stack traces or interfere with global error handlers. Fix: Treat error objects as immutable. If additional context is needed, create a new error instance or pass metadata through a separate context object or closure.

6. Using finally for Control Flow

Explanation: finally executes after try/catch, but if it contains a return or throw, it overrides the original outcome. This silently discards errors or return values, breaking predictable execution. Fix: Restrict finally to cleanup operations only. Never place return, throw, or state mutations that affect the function's output inside finally.

7. Cross-Realm instanceof Failures

Explanation: In environments with multiple global contexts (iframes, Web Workers, Node.js VMs), instanceof fails because each realm has its own Error constructor. A DataParsingError created in one realm won't match instanceof DataParsingError in another. Fix: Use error codes or custom string properties for routing instead of instanceof. Check error.errorCode === 'DATA_PARSE_FAILURE' or verify error.name for cross-realm compatibility.

Production Bundle

Action Checklist

• Audit existing catch blocks: Ensure every catch logs, returns a fallback, or re-throws. Remove silent swallowers.
• Implement a base error class: Add errorCode, isOperational, and captureStackTrace to standardize error metadata.
• Centralize error routing: Create a single dispatcher function that maps error types to recovery actions (RETRY, FALLBACK, ABORT).
• Boundary-wrap async operations: Place try/catch/finally at service or feature boundaries, not individual statements.
• Enforce finally cleanup rules: Verify all finally blocks only handle resource release, never control flow or return overrides.
• Add static analysis guards: Configure TypeScript strict mode and ESLint rules to catch unhandled promise rejections and syntax issues pre-runtime.
• Instrument observability: Emit error codes, stack traces, and operational flags to your monitoring pipeline for automated alerting.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
User input validation	Throw custom ValidationError with immediate fallback	Prevents downstream processing of malformed data; keeps UI responsive	Low (minimal overhead)
External API call failure	Throw ExternalServiceError with status code; route to retry queue	Enables exponential backoff and circuit breaker patterns without blocking main thread	Medium (retry infrastructure)
Critical database transaction	Wrap in try/catch/finally; re-throw on failure; use finally for connection release	Guarantees data consistency and prevents connection pool exhaustion	High (requires transaction management)
Third-party library integration	Catch generic Error, extract message/stack, wrap in custom error	Isolates external instability; prevents vendor-specific errors from leaking into core logic	Low (wrapper overhead)
Batch processing (100+ items)	Use Promise.allSettled() instead of try/catch per item	Prevents single failure from aborting entire batch; collects all results for partial success	Medium (memory for result aggregation)

Configuration Template

// error-handling.config.ts
import { BaseRuntimeError } from './BaseRuntimeError';

export const ErrorRoutingConfig = {
  maxRetryAttempts: 3,
  retryBackoffMs: 1000,
  operationalErrorCodes: [
    'DATA_PARSE_FAILURE',
    'EXTERNAL_SERVICE_DOWN',
    'RATE_LIMIT_EXCEEDED',
    'TIMEOUT_OCCURRED'
  ],
  logLevel: process.env.NODE_ENV === 'production' ? 'error' : 'debug',
  
  // Cross-realm safe type guard
  isOperationalError(error: unknown): boolean {
    if (!(error instanceof Error)) return false;
    const typedError = error as BaseRuntimeError;
    return (
      'isOperational' in typedError &&
      typedError.isOperational === true
    );
  },

  // Safe stack extraction for logging
  extractDiagnosticInfo(error: unknown) {
    if (!(error instanceof Error)) return { message: String(error) };
    return {
      name: error.name,
      message: error.message,
      stack: error.stack?.split('\n').slice(0, 5).join('\n'), // Truncate for payload size
      code: (error as BaseRuntimeError).errorCode ?? 'UNKNOWN'
    };
  }
};

Quick Start Guide

1. Initialize the base error class: Copy the BaseRuntimeError implementation into your project. Ensure Error.captureStackTrace is called in the constructor to maintain clean stack traces.
2. Define domain-specific errors: Create 2-3 custom error classes matching your application's failure modes (e.g., NetworkTimeoutError, SchemaValidationError). Attach relevant context properties.
3. Create the routing dispatcher: Implement a function that accepts unknown, checks error codes or properties, and returns a deterministic action enum. Wire this to your logging/metrics provider.
4. Wrap your first boundary: Identify a high-risk async function (API call, file read, JSON parse). Surround it with try/catch/finally. Route caught errors through the dispatcher. Use finally strictly for cleanup.
5. Validate in staging: Trigger failures intentionally (malformed payloads, network throttling, missing dependencies). Verify that the main thread continues, resources are released, and observability tools receive structured error payloads.