JavaScript Error Handling Complete Guide

Error handling is one of the most critical aspects of building reliable JavaScript applications. A well-designed error handling strategy prevents crashes, provides meaningful feedback to users, and gives developers the information they need to diagnose and fix problems. Yet error handling is often an afterthought, bolted on after the happy path is implemented. This guide takes a systematic approach, covering the language primitives, patterns for synchronous and asynchronous code, custom error hierarchies, and production monitoring strategies.

Whether you are building interactive user interfaces with React hooks and patterns, writing server-side APIs, or automating deployments through Jenkins pipelines, robust error handling separates production-quality code from prototypes. JavaScript's dynamic nature means that many errors that would be caught at compile time in statically typed languages only surface at runtime, making defensive error handling even more important.

What You Will Learn

This guide covers JavaScript error handling from basic try/catch mechanics to production-grade error monitoring strategies. You will learn to create custom error hierarchies, handle async errors reliably, and implement error boundaries that prevent cascading failures in complex applications.

Prerequisites

You should understand JavaScript functions, objects, and prototype inheritance. Familiarity with promises and async/await syntax is required for the async error handling sections. Basic experience with Node.js or browser console debugging will help you follow the practical examples.

Concept Overview

JavaScript errors are objects that carry a message, stack trace, and optional cause chain. The language provides try/catch/finally for synchronous error handling and promise rejection for async flows. Effective error handling requires distinguishing between operational errors that can be recovered from and programmer errors that indicate bugs needing fixes.

Step-by-Step Explanation

The sections below progress from fundamental error mechanics through custom error classes to production monitoring patterns. Each topic includes practical code examples that demonstrate both the problem and the recommended solution approach.

Error Types and the Error Object

JavaScript has a built-in Error class and several subclasses that represent different categories of runtime errors. Understanding these types helps you write targeted catch blocks and create meaningful custom errors that integrate with the language's error infrastructure.

The base Error class has three standard properties: message, which is the human-readable description passed to the constructor; name, which defaults to "Error" but is overridden by subclasses; and stack, which is a non-standard but universally supported property containing the stack trace at the point where the error was created. The stack trace is invaluable for debugging because it shows the exact call chain that led to the error.

TypeError is thrown when a value is not of the expected type. This is the most common runtime error in JavaScript applications. Calling a method on undefined, accessing properties of null, and passing the wrong argument type to built-in functions all produce TypeErrors. In production applications, TypeErrors often indicate missing null checks or incorrect assumptions about API response shapes.

ReferenceError occurs when you reference a variable that does not exist in the current scope. This typically indicates a typo in a variable name, a missing import, or an attempt to use a variable before its declaration in the temporal dead zone. Modern linters catch most ReferenceErrors before runtime, but they can still occur with dynamic property access and eval.

SyntaxError is thrown during parsing, before any code executes. You cannot catch a SyntaxError with try/catch in the same script because the script fails to parse entirely. However, SyntaxErrors from eval(), new Function(), and JSON.parse() are catchable because they occur during runtime evaluation of a string.

RangeError indicates that a numeric value is outside its allowed range. Common triggers include creating an array with a negative length, calling toFixed() with a precision greater than 100, and infinite recursion that exceeds the maximum call stack size. The stack overflow error is technically a RangeError in most engines.

URIError is thrown by encodeURI(), decodeURI(), and related functions when given malformed URI components. EvalError exists for historical reasons but is no longer thrown by modern engines. Both are rare in practice but worth knowing about for completeness.

// Examining error properties and stack traces
function processUserInput(input) {
  if (typeof input !== 'string') {
    throw new TypeError(`Expected string, received ${typeof input}`);
  }
  if (input.length === 0) {
    throw new RangeError('Input must not be empty');
  }
  return input.trim().toLowerCase();
}
 
function handleRequest(data) {
  try {
    const result = processUserInput(data.username);
    return { success: true, username: result };
  } catch (error) {
    // Access error properties for logging
    console.error(`[${error.name}] ${error.message}`);
    console.error(`Stack: ${error.stack}`);
 
    // Type-specific handling
    if (error instanceof TypeError) {
      return { success: false, code: 'INVALID_TYPE', message: error.message };
    }
    if (error instanceof RangeError) {
      return { success: false, code: 'INVALID_RANGE', message: error.message };
    }
    // Re-throw unexpected errors
    throw error;
  }
}
 
// Error cause chaining (ES2022)
function fetchConfig(path) {
  try {
    const content = readFileSync(path, 'utf-8');
    return JSON.parse(content);
  } catch (error) {
    throw new Error(`Failed to load config from ${path}`, { cause: error });
  }
}

The cause property, introduced in ES2022, allows you to chain errors while preserving the original error context. When you catch a low-level error and throw a higher-level error, attaching the original as the cause creates a chain that debugging tools can traverse. This is far better than string concatenation of error messages because it preserves the original stack trace and error type.

The AggregateError class, introduced alongside Promise.any, holds multiple errors in its errors property. This is useful when multiple operations can fail independently and you want to report all failures rather than just the first one. Validation functions that check multiple fields and batch operations that process multiple items are natural use cases for AggregateError.

Try Catch and Control Flow

The try/catch/finally statement is JavaScript's primary mechanism for handling synchronous errors. The try block contains code that might throw. The catch block handles the error if one occurs. The finally block runs regardless of whether an error was thrown, making it ideal for cleanup operations like closing connections or releasing resources.

The catch block receives the error object as its parameter. In modern JavaScript, you can omit the parameter if you do not need to inspect the error: catch { ... }. This is useful when you want to suppress an error entirely or when the error handling logic does not depend on the specific error.

A critical rule of try/catch is that it only catches synchronous errors thrown within the try block. It does not catch errors thrown inside callbacks, setTimeout handlers, or promise rejections. For asynchronous error handling, you need different patterns depending on whether you are using callbacks, promises, or async/await.

The finally block executes after both the try and catch blocks, regardless of the outcome. If the try block completes normally, finally runs before the function returns. If an error is caught, finally runs after the catch block. If an error is not caught and propagates up, finally still runs before the error leaves the function. This guarantee makes finally the right place for resource cleanup.

Be careful with return statements in finally blocks. A return in finally overrides any return in the try or catch block. Similarly, a throw in finally overrides any pending exception. This behavior is rarely intentional and can mask errors, so avoid return and throw in finally blocks unless you have a specific reason.

Nested try/catch blocks are sometimes necessary but often indicate that a function is doing too much. Each try/catch should handle errors at the appropriate abstraction level. Low-level functions should throw domain-specific errors. Mid-level functions should catch, wrap, and re-throw. High-level functions should catch and handle errors by logging, displaying user messages, or triggering recovery logic.

The performance impact of try/catch is negligible in modern engines when no error is thrown. The old advice to avoid try/catch in hot loops is outdated. However, throwing and catching errors is expensive because the engine must capture a stack trace. Do not use exceptions for control flow in performance-critical code. Reserve them for truly exceptional conditions.

Custom Error Classes and Hierarchies

Custom error classes let you create domain-specific error types that carry structured information beyond a message string. They integrate with instanceof checks, enabling type-specific error handling in catch blocks. A well-designed error hierarchy makes your application's failure modes explicit and documentable.

Custom errors should extend the built-in Error class or one of its subclasses. The constructor should call super with the message, set the name property to the class name, and attach any additional context as properties. Setting the name property ensures that the error displays correctly in stack traces and logging output.

A common pattern is to create a base application error class that all custom errors extend. This base class can include shared functionality like error codes, HTTP status mappings, serialization methods, and whether the error is operational or a programmer mistake. Operational errors are expected failures like network timeouts and validation failures. Programmer errors are bugs like null pointer dereferences and type mismatches.

// Custom error hierarchy for a web application
class AppError extends Error {
  constructor(message, options = {}) {
    super(message, { cause: options.cause });
    this.name = this.constructor.name;
    this.code = options.code || 'INTERNAL_ERROR';
    this.statusCode = options.statusCode || 500;
    this.isOperational = options.isOperational ?? true;
    this.context = options.context || {};
  }
 
  toJSON() {
    return {
      name: this.name,
      message: this.message,
      code: this.code,
      statusCode: this.statusCode,
      context: this.context,
    };
  }
}
 
class ValidationError extends AppError {
  constructor(message, fields = []) {
    super(message, { code: 'VALIDATION_ERROR', statusCode: 400 });
    this.fields = fields;
  }
}
 
class NotFoundError extends AppError {
  constructor(resource, identifier) {
    super(`${resource} not found: ${identifier}`, {
      code: 'NOT_FOUND',
      statusCode: 404,
      context: { resource, identifier },
    });
  }
}
 
class AuthenticationError extends AppError {
  constructor(message = 'Authentication required') {
    super(message, { code: 'UNAUTHENTICATED', statusCode: 401 });
  }
}
 
class RateLimitError extends AppError {
  constructor(retryAfter) {
    super(`Rate limit exceeded. Retry after ${retryAfter}s`, {
      code: 'RATE_LIMITED',
      statusCode: 429,
      context: { retryAfter },
    });
  }
}
 
// Usage in an API handler
async function getUser(id) {
  if (!id || typeof id !== 'string') {
    throw new ValidationError('Invalid user ID', [
      { field: 'id', message: 'Must be a non-empty string' }
    ]);
  }
 
  const user = await database.findUser(id);
  if (!user) {
    throw new NotFoundError('User', id);
  }
 
  return user;
}
 
// Centralized error handler
function handleError(error, req, res) {
  if (error instanceof AppError && error.isOperational) {
    res.status(error.statusCode).json(error.toJSON());
  } else {
    // Programmer error - log and return generic message
    console.error('Unexpected error:', error);
    res.status(500).json({ message: 'Internal server error' });
  }
}

The distinction between operational and programmer errors is crucial for production systems. Operational errors should be handled gracefully with appropriate user feedback and possibly retry logic. Programmer errors indicate bugs that should be fixed in code. In Node.js, some teams choose to crash and restart the process on programmer errors to avoid running in a potentially corrupted state.

Error codes provide a stable identifier that client code can match against without parsing error messages. Messages are for humans and may change between versions. Codes are for machines and should remain stable. Use string codes rather than numeric codes because they are self-documenting and less likely to collide.

Async Error Handling Patterns

Asynchronous error handling requires different approaches depending on the async pattern in use. Callbacks, promises, and async/await each have their own error propagation semantics. Mixing patterns without understanding these differences leads to swallowed errors and difficult-to-debug failures.

In the callback pattern, errors are passed as the first argument to the callback function. This convention, known as error-first callbacks, is universal in Node.js core APIs. The caller must check for the error before processing the result. If the caller forgets to check, the error is silently ignored. This fragility is one reason the JavaScript community moved toward promises.

Promise rejection is the async equivalent of throwing an exception. A rejected promise propagates through the chain until it finds a catch handler. If no handler exists, the rejection becomes an unhandled promise rejection. Node.js versions 15 and later terminate the process on unhandled rejections by default, treating them as seriously as uncaught exceptions.

Async/await transforms promise rejections into thrown exceptions that you can catch with standard try/catch. This is the most ergonomic pattern for error handling in async code because it uses the same syntax as synchronous error handling. However, you must remember that await only catches rejections from the awaited promise. If you start a promise without awaiting it, its rejection will not be caught by the surrounding try/catch.

A common mistake is creating floating promises, promises that are neither awaited nor have a catch handler attached. These are dangerous because their rejections are unhandled. Linting rules like no-floating-promises in TypeScript's ESLint plugin catch this pattern. Always either await a promise, attach a catch handler, or explicitly void it if you intentionally want to ignore its result.

// Comprehensive async error handling patterns
class ApiClient {
  #baseUrl;
  #timeout;
 
  constructor(baseUrl, timeout = 5000) {
    this.#baseUrl = baseUrl;
    this.#timeout = timeout;
  }
 
  async request(path, options = {}) {
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), this.#timeout);
 
    try {
      const response = await fetch(`${this.#baseUrl}${path}`, {
        ...options,
        signal: controller.signal,
        headers: {
          'Content-Type': 'application/json',
          ...options.headers,
        },
      });
 
      if (!response.ok) {
        const body = await response.text().catch(() => '');
        throw new AppError(`HTTP ${response.status}: ${response.statusText}`, {
          code: 'HTTP_ERROR',
          statusCode: response.status,
          context: { path, body },
        });
      }
 
      return await response.json();
    } catch (error) {
      if (error.name === 'AbortError') {
        throw new AppError(`Request timeout after ${this.#timeout}ms`, {
          code: 'TIMEOUT',
          statusCode: 408,
          cause: error,
          context: { path, timeout: this.#timeout },
        });
      }
      if (error instanceof AppError) {
        throw error;
      }
      throw new AppError('Network request failed', {
        code: 'NETWORK_ERROR',
        statusCode: 503,
        cause: error,
        context: { path },
      });
    } finally {
      clearTimeout(timeoutId);
    }
  }
 
  async requestWithRetry(path, options = {}, maxRetries = 3) {
    let lastError;
    for (let attempt = 1; attempt <= maxRetries; attempt++) {
      try {
        return await this.request(path, options);
      } catch (error) {
        lastError = error;
        if (!this.#isRetryable(error) || attempt === maxRetries) {
          throw error;
        }
        const delay = Math.min(1000 * Math.pow(2, attempt - 1), 10000);
        await new Promise(resolve => setTimeout(resolve, delay));
      }
    }
    throw lastError;
  }
 
  #isRetryable(error) {
    if (error instanceof AppError) {
      return [408, 429, 500, 502, 503, 504].includes(error.statusCode);
    }
    return true;
  }
}

Global error handlers serve as the last line of defense. In browsers, the window.onerror handler catches uncaught synchronous errors, and window.onunhandledrejection catches unhandled promise rejections. In Node.js, process.on('uncaughtException') and process.on('unhandledRejection') serve the same purpose. These handlers should log the error, report it to a monitoring service, and in Node.js, gracefully shut down the process.

Error boundaries in React are class components that catch errors during rendering, in lifecycle methods, and in constructors of the whole tree below them. They do not catch errors in event handlers, async code, or server-side rendering. For applications built with React, error boundaries are essential for preventing a single component failure from crashing the entire application.

Production Error Monitoring

Handling errors in development is straightforward because you have access to the console, debugger, and source maps. Production error monitoring requires a different approach: structured logging, error aggregation, alerting, and the ability to reproduce issues from the information captured at the time of failure.

Structured logging replaces unstructured console.log calls with JSON-formatted log entries that include timestamp, severity level, error details, request context, and correlation IDs. Structured logs are searchable, filterable, and parseable by log aggregation tools. Every error log should include enough context to understand what the application was doing when the error occurred.

Error aggregation services like Sentry, Datadog, and Bugsnag collect errors from production, deduplicate them, track their frequency, and alert when new errors appear or existing ones spike. They capture stack traces, breadcrumbs of recent events, user context, and environment information. Integrating an error monitoring service is one of the highest-value investments for production applications.

Source maps enable readable stack traces in production even when your code is minified and bundled. Upload source maps to your error monitoring service during deployment, but do not serve them publicly. This gives you full stack traces with original file names and line numbers without exposing your source code to users.

Correlation IDs link related log entries across services and async boundaries. Generate a unique ID at the entry point of each request and propagate it through all function calls, async operations, and service-to-service communications. When an error occurs, the correlation ID lets you trace the complete request path and understand the full context of the failure.

Health checks and readiness probes complement error monitoring by detecting systemic failures. A health check endpoint verifies that the application can reach its dependencies like databases and external APIs. When health checks fail, orchestration systems like Kubernetes can restart the container or route traffic away from the unhealthy instance. For applications deployed with Docker, health checks are configured in the Dockerfile or deployment manifest.

Rate limiting error reports prevents your monitoring service from being overwhelmed during cascading failures. If a dependency goes down and every request generates an error, you might produce thousands of identical error reports per second. Client-side rate limiting in your error reporting library ensures you capture the error pattern without flooding the service.

When building applications on JavaScript fundamentals and deploying them to production, error handling is not optional. Every external interaction, whether it is a network request, file system operation, or user input, can fail. Design your error handling strategy early, implement it consistently, and monitor it continuously. The investment pays for itself the first time you diagnose a production issue in minutes instead of hours.

Real-World Use Cases

API servers use structured error handling to return appropriate HTTP status codes while logging detailed diagnostics for debugging. Frontend applications implement error boundaries to isolate component failures and display fallback UI instead of crashing the entire page. CLI tools use custom error classes to distinguish between user input errors and internal failures, providing actionable messages for each case.

Best Practices

Throw errors early and catch them at the appropriate boundary where you have enough context to handle them meaningfully. Include the original error as the cause property when wrapping errors to preserve the full diagnostic chain. Use structured logging with error codes so monitoring systems can aggregate and alert on specific failure categories.

Common Mistakes

Catching errors without rethrowing or logging them silently hides bugs that surface later in unexpected ways. Using generic catch blocks that handle all error types identically prevents proper recovery logic for different failure modes. Forgetting to handle promise rejections in Node.js leads to process crashes in production when unhandledRejection events fire.

Summary

Robust error handling requires a deliberate strategy that covers synchronous code, async operations, and cross-boundary communication. Custom error hierarchies enable precise handling logic while structured logging and monitoring ensure that production issues are detected and diagnosed quickly. Investing in error handling infrastructure pays dividends through faster debugging and more resilient applications.