Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Primitive and Special Types

TypeScript Error type and custom error classes

Reference for Error in TypeScript: built-in error classes, writing custom error classes, the cause option, why caught values are unknown, and instanceof checks.

Error is the base class for runtime errors. Its type has three members you can rely on: name, message and an optional stack. Built-in subclasses include TypeError, RangeError, SyntaxError, ReferenceError, EvalError, URIError and AggregateError. You can throw any value in JavaScript, but throwing Error objects keeps stack traces and makes handling predictable.

The important TypeScript detail is on the catching side. With strict (through useUnknownInCatchVariables) the variable in catch (e) has type unknown, because anything can be thrown. You narrow it with instanceof Error before you read .message.

TypeScript
class NotFoundError extends Error {
  name = "NotFoundError";
}

Try it

TypeScript Narrowing caught values

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript Custom errors with cause

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Syntax

TypeScript
interface Error {
  name: string;
  message: string;
  stack?: string;
  cause?: unknown;       // ES2022
}
interface ErrorOptions {
  cause?: unknown;
}
interface ErrorConstructor {
  new (message?: string, options?: ErrorOptions): Error;
  (message?: string, options?: ErrorOptions): Error;
}
Name Description
message Human-readable description. Defaults to an empty string.
options.cause The underlying error or value that triggered this one. Stored on error.cause.
name Class name shown in traces. Subclasses should set it, because the inherited value is "Error".

Returns: the Error constructor works with or without new; the result is the same.

Edge cases: in a catch clause the variable is unknown; finally has no variable. An AggregateError takes an iterable of errors first and a message second, and exposes them as errors: any[].

Usage notes

  • When you target ES2015 or later, class MyError extends Error works as expected, including instanceof. Targeting ES5 breaks the prototype chain; there you must call Object.setPrototypeOf(this, MyError.prototype).
  • Declare extra data as typed fields (like status) so handlers can read them after narrowing.
  • Use cause to chain errors instead of losing the original; it requires the ES2022 lib or newer.
  • Do not cast catch (e) to any just to read .message. Write a small helper, such as e instanceof Error ? e.message : String(e).
  • Errors from other realms (iframes, vm contexts) fail instanceof Error. A structural check on message is the fallback in those cases.
  • Error.captureStackTrace is a V8 extension. It is typed by @types/node, not by the standard lib, so avoid relying on it in portable code.
  • Errors do not survive JSON.stringify (their fields are not enumerable); copy the fields you need into a plain object first.
  • A promise rejection reason is any in Promise.catch callbacks and unknown in try/catch around await.