Error handling in JavaScript

This chapter follows Destructuring and spread.

Runtime errors versus static checks

TypeScript and other transpilers report compile-time issues before JavaScript runs. Plain JavaScript is parsed and executed just in time: invalid syntax throws SyntaxError at parse time; bad operations at runtime throw typed Error subclasses. There is no separate “checked exception” mechanism— callers choose whether to catch or let errors propagate to the host.

Common built-in types:

try, catch, and finally

try runs a block. catch receives the thrown value (usually an Error instance). finally runs on both success and failure—use it for cleanup that must run regardless of return or throw.

1
try {
2
  risky();
3
} catch (err) {
4
  console.error(`${err.name}: ${err.message}`);
5
} finally {
6
  cleanup();
7
}

Creating an Error without throw does not stop execution—only throw begins unwinding.

1
try {
2
  throw new Error("Whoops!");
3
} catch (e) {
4
  console.error(e.message);
5
}

The Error object and cause

Error instances expose message, name, and (in most engines) stack. ES2022 added cause in the options object to chain errors when rethrowing or wrapping.

1
try {
2
  parsePayload(raw);
3
} catch (err) {
4
  throw new Error("Invalid payload", { cause: err });
5
}
6

7
try {
8
  load();
9
} catch (wrapped) {
10
  console.log(wrapped.cause); // original parse error
11
}

cause is intended for logging and inspection; console output may not expand it automatically.

Throwing your own errors

Use throw new TypeError(...) (or another built-in type) when the failure matches a standard category. Include a clear message; attach cause when translating low-level failures.

1
if (Number.isNaN(month)) {
2
  throw new TypeError("Month should be a number", { cause: { month } });
3
}

Custom Error subclasses

Extend Error for domain-specific failures. Set this.name, call super(message, options), and on V8 use Error.captureStackTrace(this, Constructor) so stacks point at your throw site.

1
class ValidationError extends Error {
2
  constructor(field, message, options) {
3
    super(message, options);
4
    this.name = "ValidationError";
5
    this.field = field;
6
    if (Error.captureStackTrace) {
7
      Error.captureStackTrace(this, ValidationError);
8
    }
9
  }
10
}
11

12
try {
13
  throw new ValidationError("email", "Invalid format");
14
} catch (e) {
15
  if (e instanceof ValidationError) {
16
    console.error(e.field, e.message);
17
  } else {
18
    throw e;
19
  }
20
}

Prefer instanceof (or err.name when crossing realms) over comparing message strings.

Rethrowing with cause

Catch, add context, and rethrow so upper layers see one message while cause preserves the original for logs or retries.

1
function doWork() {
2
  try {
3
    doFailSomeWay();
4
  } catch (err) {
5
    throw new Error("Failed in some way", { cause: err });
6
  }
7
}
8

9
try {
10
  doWork();
11
} catch (err) {
12
  handleFailSomeWay(err.cause);
13
}

Re-throw unchanged errors you do not handle (throw e in a catch) so global handlers still run.

AggregateError

AggregateError groups multiple errors—Promise.any rejects with it when every input promise fails; each reason appears in errors.

1
const failures = [new Error("a"), new Error("b")];
2
const agg = new AggregateError(failures, "All rejected");
3
console.log(agg.errors.length); // 2

Use it when your API performs parallel work and must report every failure, not only the first.

Async errors

Promises reject with whatever you pass to reject or throw inside an async executor. async/await maps rejections to catch on the awaited promise or to try/catch around await.

1
async function run() {
2
  try {
3
    await fetchBroken();
4
  } catch (err) {
5
    console.log("Caught", err.message);
6
  }
7
}
8

9
fetchBroken().catch((err) => console.log("Caught", err.message));

Unhandled promise rejections behave like uncaught exceptions in Node and browsers—register process or window handlers in servers and apps.

This is the last chapter in Language Basics. Earlier material lives under JavaScript syntax at a glance.