Error Handling

try/catch/finally, the built-in Error types, throwing your own errors, and how to read a JavaScript error message.

What it is, in plain English: An error is JavaScript's way of telling you something went wrong — a file wasn't found, a network request failed, a user typed the wrong thing. Without error handling, a single error crashes your entire program. try/catch lets you catch an error and decide what to do: show a friendly message, try again, log it, or handle it gracefully. Reading and understanding JavaScript error messages is one of the most important skills a beginner can build.

Where this bites you

finally always runs, and that includes its own return. A return inside finally replaces whatever the try or catch was doing, including an error that was in the middle of being thrown. The error simply vanishes: the caller gets a normal return value, nothing reaches any catch, and nothing is logged.

function saveOrder(order) {
  try {
    if (!order.items.length) throw new Error("order has no items");
    return "saved";
  } finally {
    console.log("closing connection");
    return "done";              // overrides the throw above
  }
}

console.log(saveOrder({ items: [] }));
// closing connection
// done          <- the "order has no items" error is gone

When things go wrong — and how to handle it

Every program encounters errors: a user types something unexpected, a network request fails, a file doesn't exist. Without error handling, a single problem crashes the entire program. try/catch lets you catch errors and handle them gracefully — show a helpful message, try something else, or at least log what went wrong.

Reading a JavaScript error

Before you can handle errors, you need to read them. Open your browser console — every error has three key pieces:

// Uncaught TypeError: Cannot read properties of undefined (reading 'name')
//         ↑ type         ↑ what happened                        ↑ detail
//     at getUserName (app.js:12)
//     at main (app.js:25)
//         ↑ stack trace — where in your code it happened

The type tells you what category of error it is. The message tells you what went wrong. The stack trace tells you exactly which line caused it.

try / catch — catch an error and handle it

try {
  // Code that might fail goes here
  const data = JSON.parse("this is not valid JSON");
  console.log(data.name);
} catch (error) {
  // If anything in try throws an error, execution jumps here
  console.error("Something went wrong:", error.message);
  // The program continues normally after the catch block
}

console.log("Program keeps running");

How it works:

JavaScript runs the code inside try { }
If an error occurs, it immediately jumps to catch — no further lines in try run
The error variable holds the Error object with .message and .name
After catch, the program continues normally

finally — code that always runs

function readFile(filename) {
  console.log("Opening file...");
  try {
    // Imagine this could fail:
    if (!filename.endsWith(".txt")) {
      throw new Error("Only .txt files are supported");
    }
    console.log("File read successfully");
    return "file contents";
  } catch (error) {
    console.error("Error:", error.message);
    return null;
  } finally {
    // This ALWAYS runs — whether try succeeded or catch ran
    console.log("Closing file... (always happens)");
  }
}

readFile("notes.txt");   // succeeds — finally still runs
readFile("image.png");   // fails — finally still runs

The example above uses finally the right way: for cleanup only, with the return statements in try and catch. Keep finally free of return (and of throw, which would replace the original error the same way), and the error carries on to the caller:

function saveOrder(order) {
  try {
    if (!order.items.length) throw new Error("order has no items");
    return "saved";
  } finally {
    console.log("closing connection");   // cleanup only -- no return here
  }
}

try {
  console.log(saveOrder({ items: [] }));
} catch (e) {
  console.log("caught:", e.message);   // caught: order has no items
}

throw — create your own errors

function setAge(age) {
  if (typeof age !== "number") {
    throw new TypeError("Age must be a number");
  }
  if (age < 0 || age > 150) {
    throw new RangeError(`Age ${age} is not a valid age`);
  }
  return age;
}

try {
  setAge("thirty");  // throws TypeError
} catch (e) {
  console.error(e.name + ":", e.message);
  // "TypeError: Age must be a number"
}

try {
  setAge(200);       // throws RangeError
} catch (e) {
  console.error(e.name + ":", e.message);
  // "RangeError: Age 200 is not a valid age"
}

The built-in Error types

TypeError

Wrong type used. Most common: accessing a property on null or undefined.

null.name "abc".sort()

ReferenceError

Using a variable that doesn't exist in scope.

console.log(x) before declaring x

SyntaxError

Code that JavaScript can't parse. Usually a typo.

Missing bracket, wrong quote

RangeError

A number is outside an allowed range.

new Array(-1)

URIError

Malformed URI in decodeURI or encodeURI.

decodeURI("%")

EvalError

Historical — rarely seen in practice today.

Legacy eval() issues

Try It Yourself

// Basic try/catch — handle an error gracefully
function divide(a, b) {
  if (b === 0) {
    throw new Error("Cannot divide by zero");
  }
  return a / b;
}

try {
  console.log(divide(10, 2));   // 5 — works fine
  console.log(divide(10, 0));   // throws — goes to catch
  console.log("This line never runs");
} catch (error) {
  console.error("Caught:", error.message);   // "Caught: Cannot divide by zero"
} finally {
  console.log("finally always runs");
}

// Different error types
try {
  null.property;   // TypeError
} catch (e) {
  console.log(e instanceof TypeError);  // true
  console.log(e.name);                  // "TypeError"
  console.log(e.message);              // "Cannot read properties of null"
}

// Catching JSON parse errors
function parseJSON(text) {
  try {
    return JSON.parse(text);
  } catch (e) {
    console.error("Invalid JSON:", e.message);
    return null;
  }
}

console.log(parseJSON('{"name":"Alice"}'));  // { name: "Alice" }
console.log(parseJSON("not valid json"));   // logs error, returns null

Custom error classes, error chaining, and async error handling

Custom error classes

// Extend Error to create domain-specific error types:
class ValidationError extends Error {
  constructor(field, message) {
    super(message);          // pass message to Error
    this.name = "ValidationError";
    this.field = field;      // add custom property
  }
}

class NetworkError extends Error {
  constructor(statusCode, message) {
    super(message);
    this.name = "NetworkError";
    this.statusCode = statusCode;
  }
}

function validateEmail(email) {
  if (!email.includes("@")) {
    throw new ValidationError("email", `"${email}" is not a valid email`);
  }
}

try {
  validateEmail("not-an-email");
} catch (e) {
  if (e instanceof ValidationError) {
    console.log(`Validation failed on field '${e.field}': ${e.message}`);
  } else {
    throw e;  // re-throw errors you can't handle
  }
}

Error chaining — cause (ES2022)

// Wrap a low-level error in a higher-level one, preserving the original:
try {
  JSON.parse("invalid");
} catch (original) {
  throw new Error("Failed to load config", { cause: original });
  // error.cause points to the original SyntaxError
}

Async error handling — try/catch with async/await

// async functions return Promises — try/catch works seamlessly:
async function fetchUser(id) {
  try {
    const response = await fetch(`/api/users/${id}`);
    if (!response.ok) {
      throw new NetworkError(response.status, `User ${id} not found`);
    }
    return await response.json();
  } catch (e) {
    if (e instanceof NetworkError) {
      console.error(`Network error ${e.statusCode}: ${e.message}`);
      return null;
    }
    throw e;   // re-throw unexpected errors
  }
}

// Multiple async calls — catch at the top level:
async function main() {
  try {
    const user = await fetchUser(1);
    const posts = await fetchUser(2);  // each await can throw
    console.log(user, posts);
  } catch (e) {
    console.error("main failed:", e.message);
  }
}
main();

Global error handlers

// Browser — catch unhandled errors:
window.addEventListener("error", (event) => {
  console.error("Unhandled error:", event.error.message);
});

window.addEventListener("unhandledrejection", (event) => {
  console.error("Unhandled Promise rejection:", event.reason);
  event.preventDefault();  // prevent browser default handling
});

// Node.js:
process.on("uncaughtException", (err) => {
  console.error("Uncaught exception:", err);
  process.exit(1);  // always exit after uncaughtException
});

process.on("unhandledRejection", (reason) => {
  console.error("Unhandled rejection:", reason);
});

The Error object internals, stack traces, and the AggregateError

Error object structure

Error instances have three own properties and access to prototype properties:

const e = new Error("something failed");
e.name;     // "Error" — from Error.prototype.name
e.message;  // "something failed" — set by constructor
e.stack;    // implementation-dependent string with stack trace

// V8 stack format:
// Error: something failed
//     at functionName (file.js:line:col)
//     at caller (file.js:line:col)

V8's Error.captureStackTrace

// In V8 (Node.js, Chrome), you can control the stack trace:
class CustomError extends Error {
  constructor(message) {
    super(message);
    this.name = "CustomError";
    // Remove CustomError constructor from the stack trace:
    if (Error.captureStackTrace) {
      Error.captureStackTrace(this, CustomError);
    }
  }
}
// Now the stack trace starts at the code that threw CustomError,
// not inside CustomError's constructor.

AggregateError (ES2021)

// AggregateError wraps multiple errors — used by Promise.any:
try {
  await Promise.any([
    Promise.reject(new Error("fail 1")),
    Promise.reject(new Error("fail 2")),
    Promise.reject(new Error("fail 3")),
  ]);
} catch (e) {
  console.log(e instanceof AggregateError);  // true
  console.log(e.errors);  // [Error: fail 1, Error: fail 2, Error: fail 3]
  console.log(e.message); // "All promises were rejected"
}

// Create your own AggregateError:
throw new AggregateError([err1, err2], "Multiple validation errors");

Error handling in the spec — Completion Records

The spec models thrown errors as Completion Records with [[Type]] = throw and [[Value]] = the thrown value. When an operation throws, its Completion Record propagates up the call stack until caught by a try statement's CatchClause. The finally block uses an UpdateEmpty/NormalCompletion mechanism to run regardless of whether the preceding Completion was normal, throw, return, break, or continue.

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.