JavaScript Error Handling Patterns

Error handling in JavaScript spans two orthogonal concerns: where failure information lives (a thrown completion versus a value in the return type) and how it propagates (sync stack, microtask queue, worker boundary, render phase, top-level handler). Most production bugs come from confusing the two — wrapping await in try/catch does nothing for a fire-and-forget Promise, and a React ErrorBoundary does not catch the onClick handler one level below it. This article maps the full pipeline: the Error type and its subclasses, Error.cause, AggregateError, AbortError, async stack traces, structured cloning across realms, browser and Node top-level handlers, React 19 boundaries, and the exception-versus-Result trade-off with neverthrow / fp-ts / Effect-TS.

Mental model

Three orthogonal axes determine how an error behaves at runtime. Pick the right axis before you reach for syntax.

Two more sub-rules collapse most of the day-to-day confusion:

• Throwing a non-Error is legal but pathological. ECMA-262 lets throw accept any value; the runtime never adds a stack to a thrown string. catch therefore must defend with a runtime check before reading .message.
• The boundary is wherever the engine takes over. Awaiting code is on your stack; the microtask reaction is on the engine’s. The Promise constructor’s executor is on your stack; a setTimeout callback inside it is on the engine’s. Reach for try/catch only where the stack is yours.

Primitives

The Error type and its subclasses

Error is the base built-in. Per ECMA-262 §20.5 it stores name, message, an [[ErrorData]] internal slot (which is what makes an object actually an error), and an optional cause. The standard subclasses cover the engine’s own throw sites:

Beyond the built-ins, browsers expose DOMException (which mimics Error but does not inherit from it pre-2023; treat its .name as the discriminator) and Node adds SystemError and AbortError shapes. Userland subclasses use the standard pattern:

1export class HttpError extends Error {2  override name = "HttpError"3  constructor(4    public readonly status: number,5    message: string,6    options?: { cause?: unknown },7  ) {8    super(message, options)9  }10}

The two correctness gotchas to know:

1. name defaults to "Error". Always override it on subclasses or instanceof checks downstream still work but log lines lie.
2. Object.setPrototypeOf is no longer needed for extends Error since ES2015 / TypeScript target: es2017. It is needed when transpiling down to ES5, where super(message) returns a fresh object that loses the prototype link. If your codebase targets modern runtimes, the historical workaround is dead code.

throw, try / catch / finally

ECMA-262 §14.15 defines the structured form:

Show 2 hidden lines3try {4  const result = riskyOperation()5  return processResult(result)6} catch (error) {7  console.error("Operation failed:", error)8  return fallbackValue9} finally {10  cleanup() // runs even after return/throw11}

Execution semantics (per ECMA-262 §14.15.3) follow the completion-record model:

1. Evaluate the try block.
2. On a ThrowCompletion, the runtime walks up the call stack searching for a matching catch.
3. If found, bind the thrown value to the catch parameter and run the catch block.
4. Run finally regardless — even when try or catch already returned or threw.

finally overrides outcomes. A return (or throw) inside finally shadows the in-flight completion. This is rarely what you want:

1function surprising() {2  try {3    throw new Error("Original error")4  } finally {5    return "finally wins" // suppresses the throw6  }7}8surprising() // "finally wins" — no error reaches the caller

Per ECMA-262 §14.14, throw accepts any value — strings, numbers, plain objects, null. Treat that as a footgun, not a feature:

Show 2 hidden lines3throw "Something went wrong" // string4throw 404                    // number5throw { code: "E_FAIL" }     // plain object6throw null                   // null — breaks error.message access78throw new Error("Something went wrong")9throw new TypeError("Expected string, got number")

Error.cause and chaining

ES2022 added cause (proposal). It replaces the old “wrap message and stash the original on .original” idiom:

1try {2  await fetchUser(id)3} catch (cause) {4  throw new Error(`Cannot load user ${id}`, { cause })5}

Both Node’s default util.inspect and the V8 console formatter render the chain as Caused by: automatically. Error.cause is preserved across structured cloning (Chrome and Firefox; WebKit’s behaviour is still underspecified) and through Node’s inspect boundaries.

AggregateError and Promise.any

AggregateError (ES2021) bundles multiple errors into one. Its sole built-in source is Promise.any, which rejects only when every input promise has rejected:

1try {2  const fastest = await Promise.any([fetch("/a"), fetch("/b"), fetch("/c")])3} catch (e) {4  if (e instanceof AggregateError) {5    for (const inner of e.errors) {6      console.warn("candidate failed:", inner)7    }8  }9}

It is also a useful userland tool: any time a function fans work out and needs to report partial-failure information, throw new AggregateError(errs, "fan-out failed") is more honest than picking one error to surface.

Async / await and Promise rejection propagation

Promises (ES2015) and async / await (ES2017) layer the throw model onto microtasks. Three rules cover the surface:

1. await rethrows. A rejected Promise resumes the async function with a thrown completion at the await site. Standard try/catch works.
2. A non-awaited, non-.catch-ed Promise is “unhandled”. The engine fires HostPromiseRejectionTracker which dispatches unhandledrejection (browser) or unhandledRejection (Node) on the next microtask drain.
3. The Promise constructor’s executor is sync-throw safe; its async callbacks are not. A throw in the executor body is converted to a rejection, but a throw inside a setTimeout inside the executor escapes — there is no handler to catch it on the engine’s stack.

Show 2 hidden lines3  throw new Error("Sync throw") // becomes rejection4})56// 2. Async throw inside executor → uncaught exception7new Promise((resolve) => {8  setTimeout(() => {9    throw new Error("Escapes!") // not catchable from this Promise10  }, 0)11})1213// 3. Concurrent await: first rejection wins; siblings keep running14const [a, b] = await Promise.all([15  fetch("/a"), // rejects16  fetch("/b"), // also rejects → handled? no — the second is "lost"17])1819// Use Promise.allSettled when you need every outcome20const settled = await Promise.allSettled([fetch("/a"), fetch("/b")])

ES2025 ships Promise.try (Stage 4, finished 2024-10-09) to collapse the sync-or-async ambiguity at any callback boundary into one rejection path:

1// Works for sync throw, async throw, and plain return.2await Promise.try(() => maybeSyncOrAsync()).catch(handle)

Reach for it whenever you wrap a callback supplied by user code or by a library you do not control — it removes the “sync exception escaped my Promise chain” footgun without an extra try/catch.

TypeScript: catch (e: unknown) and narrowing

Since TypeScript 4.4, the useUnknownInCatchVariables compiler option types catch parameters as unknown rather than any, and strict: true turns it on automatically. The change is correct: ECMA-262 lets anything be thrown, and unknown forces a guard.

1try {2  riskyOperation()3} catch (error) {4  if (error instanceof Error) {5    console.log(error.message)6  } else if (typeof error === "string") {7    console.log(error)8  } else {9    console.log("Unknown thrown value:", error)10  }11}

The standard narrowing patterns:

1export function isError(value: unknown): value is Error {2  return value instanceof Error3}45export function asError(value: unknown): Error {6  if (value instanceof Error) return value7  if (typeof value === "string") return new Error(value)8  try {9    return new Error(JSON.stringify(value))10  } catch {11    return new Error(String(value))12  }13}1415export function hasCode<T extends string>(16  value: unknown,17  code: T,18): value is Error & { code: T } {19  return value instanceof Error && (value as { code?: unknown }).code === code20}

The annotation on the catch parameter itself is restricted to unknown or any — TypeScript does not allow you to claim a more specific type at the binding site. Narrow inside the block, do not annotate at the colon.

Error.isError for cross-realm checks

Error.isError reached Stage 4 in 2025 and is included in the ECMAScript 2026 specification. It addresses the cross-realm instanceof footgun:

1const iframe = document.createElement("iframe")2document.body.appendChild(iframe)3const ForeignError = iframe.contentWindow.Error4const e = new ForeignError("from iframe")56e instanceof Error      // false — different Error constructor7Error.isError(e)        // true — checks [[ErrorData]] internal slot

The check is an internal-slot test, so subclasses created with class MyError extends Error are still detected, but a plain object that happens to have message and stack is not. Prefer Error.isError over instanceof Error in any code that crosses realms (iframes, workers, vm contexts, Node’s vm.runInNewContext).

Async stack traces

V8 ships zero-cost async stack traces (Chrome 73 / Node.js 12+, default). The engine reconstructs the suspend / resume chain across await (and Promise.all) by walking the resumption metadata it already keeps for the microtask scheduler — there is no per-await capture cost. The DevTools “stitched” stack covers more cases (setTimeout, requestAnimationFrame, raw then callbacks) but only when the inspector is attached.¹

Two practical rules:

• For raw Promise.then chains, the zero-cost mechanism does not stitch; rely on cause to carry the original frame.
• Error.stackTraceLimit defaults to 10. Bump it temporarily when debugging deep async chains; restore it to keep production overhead bounded.

AbortController, AbortSignal, and AbortError

AbortController is the standard cancellation primitive, plumbed through fetch, Request, EventTarget.addEventListener, Node’s HTTP / FS / streams APIs, and most modern libraries. It throws a DOMException named "AbortError", not a regular Error:

1const ctrl = new AbortController()2const t = setTimeout(() => ctrl.abort(new DOMException("Slow", "TimeoutError")), 5_000)3try {4  const res = await fetch(url, { signal: ctrl.signal })5  return await res.json()6} catch (e) {7  if (e instanceof DOMException && e.name === "AbortError") return null // user cancellation, not a bug8  if (e instanceof DOMException && e.name === "TimeoutError") {9    metrics.increment("fetch.timeout")10    throw e11  }12  throw new Error("fetch failed", { cause: e })13} finally {14  clearTimeout(t)15}

The modern surface to know:

• AbortSignal.timeout(ms) returns a signal that aborts with a TimeoutError DOMException.
• AbortSignal.any([s1, s2]) composes multiple signals — the first to abort wins.
• signal.throwIfAborted() is the cooperative-cancellation entry point inside long-running async work.
• signal.reason carries whatever you passed to abort(reason); pass a typed object to distinguish “user clicked cancel” from “request superseded by newer one”.

Treat AbortError as a non-failure — it represents a cooperative outcome, not a bug. Logging it as an error skews dashboards.

Structured cloning and worker error transmission

postMessage between a window and a Worker (or between iframes) runs the HTML structured-clone algorithm. Errors are explicitly clonable as of HTML Living Standard:

AggregateError.errors is recursively cloned. Userland subclasses lose their constructor and arrive on the other side as a plain Error whose name matches the original. If you need richer transport, serialise to a plain object yourself ({ name, message, stack, code, ... }) and reconstruct.

Workers expose three relevant events:

• error on the Worker instance fires when the worker throws an uncaught exception. The event is an ErrorEvent carrying message, filename, lineno, and (in modern engines) the original Error on .error.
• messageerror fires when a posted message cannot be deserialized — useful for catching cross-realm clone failures.
• unhandledrejection also fires on WorkerGlobalScope; install handlers symmetrically with the main thread.

Browser top-level handlers

The browser exposes two global error events on Window (and WorkerGlobalScope):

1window.addEventListener("error", (event: ErrorEvent) => {2  reporter.captureError(event.error ?? new Error(event.message), {3    src: event.filename,4    line: event.lineno,5  })6  // event.preventDefault() to suppress the browser's default console output7})89window.addEventListener("unhandledrejection", (event: PromiseRejectionEvent) => {10  reporter.captureError(event.reason instanceof Error ? event.reason : new Error(String(event.reason)))11  // event.preventDefault() to mark as handled — DOMException AbortError typically should be silenced12})

Two non-obvious points:

• Resource load failures don’t bubble. An <img> or <script> error event reaches window only through capture-phase listeners ({ capture: true }), because the spec says these don’t bubble.
• window.onerror (the IDL attribute) has a legacy 5-arg signature (message, source, lineno, colno, error) — don’t use it for new code; prefer addEventListener('error', ...).

Node.js top-level handlers

Node’s process events mirror the browser surface, with materially different defaults:

• uncaughtException — default behaviour: print stack to stderr and exit with code 1. Installing a listener overrides the exit; the docs are explicit that this is “for synchronous cleanup, not recovery”.
• uncaughtExceptionMonitor — fires before uncaughtException, observation only; does not prevent the crash.
• unhandledRejection — since Node 15.0.0 the default is --unhandled-rejections=throw, which converts the rejection into an uncaughtException and exits. Earlier behaviour (warn) is still selectable but should not ship in production.
• rejectionHandled — symmetric to the browser, fires when a previously-unhandled rejection gets a handler.

1process.on("unhandledRejection", (reason, promise) => {2  reporter.captureError(reason instanceof Error ? reason : new Error(String(reason)))3  throw reason // let the process die; supervisor will restart4})56process.on("uncaughtException", (err, origin) => {7  reporter.captureError(err, { origin })8  // synchronous cleanup only — close logger, flush stdout, then exit9  void shutdown(1)10})

The hard rule: never swallow uncaughtException in a long-running process. The state of the heap after an uncaught throw is undefined; the only safe action is to flush, log, and exit. Leave restart to the supervisor (systemd, Kubernetes, PM2, Docker --restart).

React 19 Error Boundaries

A React Error Boundary is a class component implementing static getDerivedStateFromError(error) (render-phase fallback) and / or componentDidCatch(error, info) (commit-phase logging). It catches errors thrown during render, constructor, and lifecycle of any descendant. It does not catch:

• Event handlers (onClick, onSubmit, …) — wrap with try/catch, or trigger a re-render that throws on the next render pass.
• Asynchronous code (setTimeout, fetch.then, raw Promises) — same workaround.
• Server-side rendering (use the framework’s SSR error hook).
• Errors inside the boundary’s own render.

React 19 added two root-level callbacks on createRoot / hydrateRoot for centralised reporting:

1import { createRoot } from "react-dom/client"23createRoot(document.getElementById("root")!, {4  onCaughtError: (error, info) => reporter.captureError(error, { caughtBy: info.componentStack }),5  onUncaughtError: (error, info) => reporter.captureError(error, { uncaught: true }),6  onRecoverableError: (error) => reporter.captureWarning(error),7})

onCaughtError fires for errors a boundary handled; onUncaughtError fires for errors no boundary handled (including the boundary’s own throw). They replace the prior pattern of patching console.error to forward errors to your reporter.

For the practical UI, use react-error-boundary — it provides <ErrorBoundary fallbackRender={...} onReset={...}>, useErrorBoundary (to throw async errors back into the boundary), and withErrorBoundary for wrapping. Pair it with route-level boundaries plus a top-level fallback so a crash in one route does not blank the whole app.

Recipes

Wrapping throwing APIs at the boundary

The integration with throwing libraries is one place where try/catch is the only correct tool. Convert at the seam, not in the middle of business logic:

1import { Result, ok, err } from "neverthrow"23class ParseError extends Error {4  override name = "ParseError"5}67export function parseJson<T>(input: string): Result<T, ParseError> {8  try {9    return ok(JSON.parse(input) as T)10  } catch (cause) {11    return err(new ParseError("invalid JSON", { cause }))12  }13}

Inside the boundary the function looks throwing; outside it the function looks Result-returning. Callers compose declaratively without re-running the conversion.

Promise.try for sync-or-async callbacks

Anywhere you accept a callback that might throw synchronously and might return a Promise, route through Promise.try so the rejection path is single:

1async function safeRun<T>(fn: () => T | Promise<T>): Promise<Result<T, Error>> {2  try {3    return ok(await Promise.try(fn))4  } catch (cause) {5    return err(cause instanceof Error ? cause : new Error(String(cause), { cause }))6  }7}

From exceptions to values: the trade-off

The choice between throw-based and return-based handling is the largest single decision in this design space.

Exception model (try/catch): Failure is a side effect. Functions have two exit paths — return and throw — but only one is in the type. Stack-trace capture and unwinding can be 10×–100× slower than a normal return on the throw path; the empty try block itself has been free in V8 since 6.x (Node 8.3+).²³

Value model (Result<T, E>): Failure is data. Functions return a discriminated union that forces callers to acknowledge both outcomes. Operations compose via .map (transform success) and .andThen (chain fallible work), with failures short-circuiting subsequent success handlers — Railway Oriented Programming.

Go-style [data, error] tuples

The cheapest “make failure visible at the call site” pattern. Useful for scripts and prototypes; a leaky abstraction at scale.

Show 2 hidden lines3}45const [user, err] = await to(fetchUser(id))6if (err) return null7return user

Why it leaks: [T | null, E | null] admits four states, not two. The type system cannot rule out [null, null] or [value, error] without a discriminant.

Result types: neverthrow, fp-ts, Effect-TS

A Result is a discriminated union with exactly two variants:

1type Result<T, E> =2  | { ok: true; value: T }3  | { ok: false; error: E }

This makes invalid states impossible at the type level. Any Err short-circuits the rest of the success track and lands in the final error sink — no recovery handler runs unless one is explicitly chained with .orElse.

neverthrow (v8.2.0, released 2025-02-21) is the pragmatic default — method-chaining API familiar to OOP developers, ergonomic ResultAsync, and a companion ESLint rule that fails the build when a Result is dropped:

1import { ok, err, Result } from "neverthrow"23function parseNumber(s: string): Result<number, string> {4  const n = parseFloat(s)5  return Number.isNaN(n) ? err("Invalid number") : ok(n)6}78const message = parseNumber("10")9  .map((x) => x * 2)10  .andThen((x) => (x > 15 ? ok(x) : err("Value too small")))11  .match(12    (value) => `Computation succeeded: ${value}`,13    (error) => `Computation failed: ${error}`,14  )

Notable v8.x changes versus v7: .orElse() can change the Ok type, safeTry accepts yield* result directly (no .safeUnwrap()), and .orTee() mirrors andTee on the error track (release notes).

fp-ts (v2.16.x, the current line) is the comprehensive functional toolkit; its Either<E, A> is the same shape under different naming (Left / Right). The killer feature there is the pipe() style and the rest of the FP ecosystem (Option, Task, Reader, …).

Migrating an existing codebase

Convert at the boundary first, expand inward.

Show 3 hidden lines4  try {5    return ok(JSON.parse(input) as T)6  } catch (e) {7    return err(e instanceof SyntaxError ? e : new SyntaxError(String(e)))8  }9}1011function processUserInput(12  input: string,13): Result<User, ParseError | ValidationError> {14  return parseJson<UserInput>(input)15    .mapErr((e) => new ParseError(e.message, { cause: e }))16    .andThen(validateUser)17}

Keep try/catch at the entry points — HTTP handlers, CLI commands, message-queue consumers — to catch any throws from code that has not been converted yet. Install eslint-plugin-neverthrow from the start so unconsumed Results are caught at PR time rather than in production.

Anti-patterns

TC39 trajectory

The headline gaps are partially being closed by the language. The state of play as of April 2026:

1const greet = (name = throw new Error("Required")) => `Hello, ${name}`2const fail = () => throw new Error("Not implemented")3const value = condition ? result : throw new Error("Failed")

Decision framework

When to use try/catch: API boundaries (parsing, third-party throwing libs), top-level safety nets (HTTP handler, CLI, worker), and React event handlers / async work that must trigger a boundary fallback.

When to use Go-style tuples: scripts, prototypes, or single-call helpers where adding a dependency is more cost than the safety buys.

When to use Result<T, E>: business logic with multiple fallible steps, data-processing pipelines, anything where “forgot to check” would cause a production incident.

When to use Effect-TS / fp-ts: the entire codebase is committed to FP and you want effects, dependency injection, fibers, and observability in one package.

Practical takeaways

• Map every code path onto the three axes (channel, phase, realm) before reaching for syntax. The bug is usually that you’re handling the wrong axis.
• Throw Error subclasses with cause, never bare values. Error.isError (ES2026) plus cause is a complete, cross-realm-safe error story for new code.
• Wrap once at the boundary, return Result everywhere inside. The boundary is where the engine takes over: HTTP handler, CLI entry, React error boundary, Worker onmessage, microtask queue.
• Treat AbortError as success. Cooperative cancellation must not page anyone.
• Install both top-level handlers and a process supervisor. Browsers: error + unhandledrejection reporting to your RUM. Node: log + flush + process.exit(1); let the supervisor restart.
• Use React 19’s onCaughtError / onUncaughtError as the single funnel for client-side reporting; pair with route-level <ErrorBoundary> so one route’s crash does not blank the whole app.
• Bump Error.stackTraceLimit only while debugging. Default 10; production should not pay for deeper captures.

Appendix

Prerequisites

• TypeScript generics, union types, discriminated unions.
• Promise / async-await mechanics; the microtask queue.
• React component lifecycle (for the boundary section).

Terminology

References

Specifications

• ECMA-262 (latest editor’s draft) — ES2026, 17th edition
• ECMA-262 (ES2025) — last published yearly snapshot
• ECMA-262 §14.15 — try Statement
• ECMA-262 §14.14 — throw Statement
• ECMA-262 §20.5 — Error Objects
• HTML Living Standard — Structured serialization

MDN

• Error
• Error.cause
• AggregateError
• Promise
• AbortController / AbortSignal
• Window error event / ErrorEvent
• Window unhandledrejection / PromiseRejectionEvent
• structuredClone()

Runtime docs

• Node.js process events
• Node.js --unhandled-rejections=throw
• Node.js node:domain deprecation (DEP0032)
• Node.js AsyncLocalStorage
• V8 — Faster async functions and zero-cost stack traces

TypeScript / React

• TypeScript — useUnknownInCatchVariables
• React 19 release notes — root error options
• React Error Boundaries (legacy docs page, still authoritative on the API)
• react-error-boundary

TC39 proposals

• Error.isError (Stage 4)
• Promise.try (Stage 4)
• Pipeline operator (Stage 2)
• Pattern matching (Stage 1)
• throw expressions (Stage 2)
• do expressions (Stage 1)
• Try Operator (Stage 0)

Libraries

• neverthrow (v8.2.0)
• eslint-plugin-neverthrow
• fp-ts (v2.16.x)
• Effect-TS
• ts-results
• oxide.ts

Practitioner content

• Railway Oriented Programming — Scott Wlaschin
• Error handling in Go
• Working with errors in Go 1.13