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.
class NotFoundError extends Error { name = "NotFoundError"; }
Try it
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.
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
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 Errorworks as expected, includinginstanceof. Targeting ES5 breaks the prototype chain; there you must callObject.setPrototypeOf(this, MyError.prototype). - Declare extra data as typed fields (like
status) so handlers can read them after narrowing. - Use
causeto chain errors instead of losing the original; it requires theES2022lib or newer. - Do not cast
catch (e)toanyjust to read.message. Write a small helper, such ase instanceof Error ? e.message : String(e). - Errors from other realms (iframes, vm contexts) fail
instanceof Error. A structural check onmessageis the fallback in those cases. Error.captureStackTraceis 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
anyinPromise.catchcallbacks andunknownintry/catcharoundawait.