🛡️ Error Handling — JavaScript & React

🧠 The Mental Model

An error in JavaScript is just an object (usually an instance of Error) that gets thrown. Throwing interrupts normal execution and the engine starts unwinding the call stack, looking for the nearest enclosing catch. If nothing catches it, it becomes an uncaught error — the script (or the current task) dies, and only global handlers can observe it.

The two big families

🏷️ The Built-in Error Types

All inherit from Error. Every instance carries three key properties: name, message, and (non-standard but universal) stack.

null.foo          // Cannot read properties of null
undefined.map()   // undefined is not a function
const x = 1; x = 2; // Assignment to constant

console.log(notDefined);
// notDefined is not defined
{ console.log(a); let a; }
// TDZ: Cannot access 'a' before init

const = 5;        // parse-time: file dies
JSON.parse('{bad}') // runtime: CATCHABLE ✅

new Array(-1);      // Invalid array length
(1.23).toFixed(500); // digits out of range
function f(){ f(); } f();
// Maximum call stack size exceeded

decodeURIComponent('%');
// URI malformed

try { await Promise.any([p1, p2]); }
catch (e) {
  e.errors // [Error, Error] — all of them
}

🎯 throw & Custom Errors

throw can throw any value — but you should always throw Error instances, because only they carry a stack trace, and tooling (Sentry, logs) depends on it.

throw 'something failed';
throw { code: 500 };
// No stack trace. instanceof
// checks impossible. Logs are
// useless: "Uncaught #<Object>"

throw new Error('Payment failed', {
  cause: originalError  // ES2022: keep the chain
});
// name + message + stack + cause ✅

Custom error classes — model your domain

Extend Error so callers can react differently to different failures using instanceof instead of string-matching messages.

class ApiError extends Error {
  constructor(message, status, { cause } = {}) {
    super(message, { cause });
    this.name = 'ApiError';   // otherwise logs say "Error"
    this.status = status;
  }
}
class ValidationError extends Error {
  constructor(message, field) { super(message); this.name = 'ValidationError'; this.field = field; }
}

// Caller reacts per type — no message string-matching:
try {
  await saveUser(form);
} catch (err) {
  if (err instanceof ValidationError) highlightField(err.field);
  else if (err instanceof ApiError && err.status === 401) redirectToLogin();
  else throw err;   // unknown → don't swallow. Re-throw! 🔑
}

🧰 try / catch / finally

The synchronous workhorse. Three blocks, each with a precise job:

try {
  // 1. Code that might throw
  const data = JSON.parse(raw);
  process(data);
} catch (err) {
  // 2. Runs ONLY if try threw. Receives the thrown value.
  if (err instanceof SyntaxError) showToast('Invalid file format');
  else throw err;
} finally {
  // 3. Runs ALWAYS — success, throw, even after a return.
  spinner.hide();       // cleanup belongs here
}

The trap everyone hits: try/catch does NOT catch async callbacks

try {
  setTimeout(() => {
    throw new Error('boom');
  }, 1000);
} catch (e) {
  // NEVER runs. The callback executes
  // on a FRESH call stack a second
  // later — this try is long gone.
}

setTimeout(() => {
  try {
    risky();
  } catch (e) {
    handle(e);   // same stack ✅
  }
}, 1000);

finally's superpowers (and one footgun)

• Runs even after return — guaranteed cleanup for locks, spinners, file handles, AbortControllers.
• Footgun: a return inside finally overrides the try's return value and swallows any in-flight exception. Never return from finally.
• ES2019: catch binding is optional — catch { } when you don't need the error object (but pause before writing an empty catch — see below).

⛓️ Errors in Promises

A rejected promise is the async equivalent of a throw. Inside a promise chain, errors propagate down the chain — skipping every .then — until they meet a .catch.

fetch('/api/user')
  .then(res => {
    if (!res.ok) throw new ApiError('Request failed', res.status);
    return res.json();   // ⚠️ fetch does NOT reject on 404/500 — only network failure!
  })
  .then(user => render(user))
  .catch(err => showError(err))     // catches network fail, bad JSON, render throw — anything above
  .finally(() => spinner.hide());

Combinators: how each one fails

// "Load the dashboard even if one widget fails" → allSettled, not all
const results = await Promise.allSettled([getUser(), getOrders(), getAds()]);
const [user, orders, ads] = results.map(r => r.status === 'fulfilled' ? r.value : null);

⏳ async / await

The gift of async/await: a rejected promise becomes a throw at the await — so plain try/catch works for async code again.

async function loadUser(id) {
  try {
    const res = await fetch(`/api/users/${id}`);
    if (!res.ok) throw new ApiError('Load failed', res.status);
    return await res.json();
  } catch (err) {
    if (err instanceof ApiError && err.status === 404) return null; // expected: handle
    throw err;                                     // unexpected: propagate
  } finally {
    stopLoading();
  }
}

The two classic async traps

try {
  saveDraft();   // no await!
} catch (e) {
  // NEVER catches. The promise
  // rejects later, outside this
  // try → unhandledrejection.
}

async function f() {
  try {
    return risky();        // ❌ escapes try
    // return await risky(); // ✅ caught here
  } catch (e) { handle(e); }
}

Inside a try, always return await — without await, the promise leaves the function unresolved and its rejection bypasses your catch.

Parallel + error handling done right

// ❌ Sequential awaits — slow, and first failure aborts silently mid-way
const user = await getUser();
const posts = await getPosts();

// ✅ Parallel, all-or-nothing (fail fast):
const [user, posts] = await Promise.all([getUser(), getPosts()]);

// ✅ Parallel, partial success allowed:
const [u, p] = await Promise.allSettled([getUser(), getPosts()]);

🌍 Global Handlers — the Last Line of Defense

Whatever slips through every local handler lands here. These are for logging/telemetry and graceful degradation — not a substitute for local handling.

// 1️⃣ Uncaught SYNCHRONOUS errors (and resource load errors with capture)
window.addEventListener('error', (event) => {
  // event.message, event.filename, event.lineno, event.error (the Error object)
  sendToSentry(event.error);
});

// 2️⃣ Unhandled PROMISE rejections — the async counterpart
window.addEventListener('unhandledrejection', (event) => {
  sendToSentry(event.reason);   // the rejection value
  event.preventDefault();        // optional: suppress console noise
});

⚛️ React Error Boundaries

By default, an uncaught error during React rendering unmounts the entire tree — white screen. An Error Boundary is a component that catches errors from the tree below it during render, and shows a fallback UI instead of killing the whole app.

The API — still class-only (by design)

class ErrorBoundary extends React.Component {
  state = { hasError: false };

  static getDerivedStateFromError(error) {
    return { hasError: true };          // render phase: switch to fallback
  }

  componentDidCatch(error, info) {
    logToService(error, info.componentStack);  // commit phase: side effects OK
  }

  render() {
    if (this.state.hasError) return this.props.fallback;
    return this.props.children;
  }
}

// Usage — granular boundaries per feature, not one giant one:
<ErrorBoundary fallback={<WidgetError />}>
  <RevenueChart />
</ErrorBoundary>

There is no hook equivalent — a function component can't be a boundary. In practice everyone uses the tiny react-error-boundary package: <ErrorBoundary FallbackComponent={…} onReset={…}> plus a useErrorBoundary() hook to forward async errors into the nearest boundary.

What boundaries catch — and famously don't

Handling what boundaries miss

// Event handler — plain try/catch:
function handleBuy() {
  try { purchase(cart); }
  catch (e) { setError(e); }        // render an error state yourself
}

// Async — catch it, then FORWARD it into the boundary via state:
const { showBoundary } = useErrorBoundary();   // react-error-boundary
useEffect(() => {
  loadData().catch(err => showBoundary(err));  // re-throws during render → caught ✅
}, []);

The trick behind showBoundary (or the DIY version — setState(() => { throw err })): move the throw back into the render phase, where the boundary can see it. Data libraries do this for you — React Query's throwOnError, and React Router's errorElement — and Suspense pairs with boundaries: promise pending → Suspense fallback; promise rejected → nearest error boundary.

Pros, cons & judgment

🏗️ Production Patterns

📋 Summary — the Whole Guide on One Screen

"Where's the throw?" → tool picker

Fifteen-second recall cards