Creating Custom Errors in JavaScript: Complete Tutorial

// Without custom errors: guessing from message strings (fragile)
try {
  await processOrder(data);
} catch (err) {
  if (err.message.includes("not found")) {
    // Fragile: what if the message changes?
  }
  if (err.message.includes("validation")) {
    // Still fragile, and easy to get wrong
  }
}
 
// With custom errors: precise, refactorable, not fragile
try {
  await processOrder(data);
} catch (err) {
  if (err instanceof NotFoundError) {
    // Typed, reliable, searchable in the codebase
  }
  if (err instanceof ValidationError) {
    // Can access err.field, err.violations, etc.
  }
}

class AppError extends Error {
  constructor(message) {
    super(message);          // Pass message to Error
    this.name = "AppError";  // Override the name property (defaults to "Error")
  }
}
 
// Test it
const err = new AppError("Something went wrong");
console.log(err.message);            // "Something went wrong"
console.log(err.name);               // "AppError"
console.log(err instanceof AppError); // true
console.log(err instanceof Error);    // true (inheritance chain)
console.log(err.stack);              // Stack trace

// Pattern A: hardcoded name (must update when class is renamed)
class NetworkError extends Error {
  constructor(message) {
    super(message);
    this.name = "NetworkError"; // Must update if class name changes
  }
}
 
// Pattern B: dynamic name (automatically reflects class name)
class NetworkError extends Error {
  constructor(message) {
    super(message);
    this.name = this.constructor.name; // "NetworkError" — always correct
  }
}
 
// Subclasses automatically get the right name:
class TimeoutError extends NetworkError {
  constructor(ms) {
    super(`Request timed out after ${ms}ms`);
    this.name = this.constructor.name; // "TimeoutError"
    this.ms = ms;
  }
}

class ValidationError extends Error {
  constructor(message, field, value) {
    super(message);
    this.name = this.constructor.name;
    this.field = field;       // Which field failed
    this.value = value;       // What value was invalid
    this.statusCode = 400;    // HTTP status for API usage
  }
}
 
class NotFoundError extends Error {
  constructor(resource, id) {
    super(`${resource} '${id}' not found`);
    this.name = this.constructor.name;
    this.resource = resource;
    this.id = id;
    this.statusCode = 404;
  }
}
 
class AuthError extends Error {
  constructor(reason = "Unauthorized") {
    super(reason);
    this.name = this.constructor.name;
    this.statusCode = 401;
  }
}
 
// Usage
function validateAge(age) {
  if (typeof age !== "number") {
    throw new ValidationError("Age must be a number", "age", age);
  }
  if (age < 0 || age > 150) {
    throw new ValidationError("Age must be between 0 and 150", "age", age);
  }
}
 
try {
  validateAge("twenty");
} catch (err) {
  if (err instanceof ValidationError) {
    console.log(err.message);  // "Age must be a number"
    console.log(err.field);    // "age"
    console.log(err.value);    // "twenty"
  }
}

// Base: all app errors
class AppError extends Error {
  constructor(message, options = {}) {
    super(message, options); // ES2022: options.cause supported
    this.name = this.constructor.name;
    this.timestamp = new Date().toISOString();
    if (Error.captureStackTrace) {
      Error.captureStackTrace(this, this.constructor);
    }
  }
}
 
// Level 2: domain categories
class DatabaseError extends AppError {}
class NetworkError extends AppError {}
class ValidationError extends AppError {
  constructor(message, violations = []) {
    super(message);
    this.violations = violations;
  }
}
 
// Level 3: specific errors
class ConnectionError extends DatabaseError {
  constructor(host) {
    super(`Cannot connect to database at ${host}`);
    this.host = host;
  }
}
 
class QueryError extends DatabaseError {
  constructor(message, query) {
    super(message);
    this.query = query;
  }
}
 
class TimeoutError extends NetworkError {
  constructor(ms, endpoint) {
    super(`Request to ${endpoint} timed out after ${ms}ms`);
    this.ms = ms;
    this.endpoint = endpoint;
  }
}
 
// Handling at different levels:
try {
  await doWork();
} catch (err) {
  if (err instanceof ValidationError) {
    // Handle validation specifically
    return showFormErrors(err.violations);
  }
  if (err instanceof DatabaseError) {
    // Handle any DB error (ConnectionError, QueryError both match)
    return showDatabaseError(err);
  }
  if (err instanceof AppError) {
    // Handle any known app error
    return showGenericError(err);
  }
  // Unknown error: rethrow
  throw err;
}

const Errors = {
  notFound: (resource, id) => new NotFoundError(resource, id),
  unauthorized: (msg) => new AuthError(msg),
  validation: (field, msg) => new ValidationError(msg, field),
  network: (msg, code) => new NetworkError(msg, code),
};
 
// Usage
throw Errors.notFound("User", userId);
throw Errors.validation("email", "Invalid email format");

// JSON.stringify misses Error properties (they're non-enumerable)
const err = new ValidationError("Invalid input", "email", "bad@");
console.log(JSON.stringify(err)); // "{}" — useless
 
// Add toJSON method for serialization
class AppError extends Error {
  constructor(message, options = {}) {
    super(message, options);
    this.name = this.constructor.name;
  }
 
  toJSON() {
    return {
      name: this.name,
      message: this.message,
      stack: this.stack,
      // Subclass properties are enumerable via spread:
      ...Object.fromEntries(
        Object.entries(this).filter(([k]) => k !== "stack")
      ),
    };
  }
}
 
// Now JSON.stringify works:
JSON.stringify(err); // {"name":"ValidationError","message":"...","field":"email",...}

// Code-based approach (common in Node.js)
class AppError extends Error {
  constructor(message, code) {
    super(message);
    this.code = code;
  }
}
 
const ErrorCodes = {
  NOT_FOUND: "NOT_FOUND",
  VALIDATION_FAILED: "VALIDATION_FAILED",
  UNAUTHORIZED: "UNAUTHORIZED",
};
 
throw new AppError("User not found", ErrorCodes.NOT_FOUND);
 
// Handling with codes:
if (err.code === ErrorCodes.NOT_FOUND) { ... }