Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Keywords and Declarations

TypeScript throw

Reference for throw in TypeScript: throwing Error objects, custom error classes, the never return type, assertion functions, throw expressions and what cannot be typed.

throw stops normal execution and hands a value to the nearest catch. JavaScript allows any value to be thrown, but you should throw Error objects (or subclasses) so you get a message and a stack trace.

TypeScript knows that code after a throw is unreachable. A function whose every path throws has the return type never, and throw participates in narrowing: after if (x == null) throw ..., the variable x is non-null for the rest of the function.

TypeScript
function fail(message: string): never {
  throw new Error(message);
}

Try it

TypeScript Throwing to narrow and to fail

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 error classes and assertion functions

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 Code after throw is dead code

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
throw expression;
throw new Error("message", { cause: original });
function f(): never { throw new Error("x"); }
Part Description
expression Any value. Use an Error or subclass.
{ cause } Optional second argument to Error (ES2022) that links the original error.
never The return type of a function that cannot complete normally.

Errors and edge cases:

  • TypeScript does not check what you throw, and there is no throws annotation.
  • A function declared to return never whose end is reachable is error TS2534 ("A function returning 'never' cannot have a reachable end point").
  • Unreachable code after throw is reported only when allowUnreachableCode is false (error TS7027); otherwise editors just grey it out.
  • A bare throw; is a syntax error. To rethrow, write throw err; inside catch.

Usage notes

  • Throw Error objects. They carry message, name and stack. Throwing strings loses the stack and confuses instanceof checks.
  • Narrowing helpers. A function returning never is treated as a terminating call only when it is declared with an explicit never return type annotation (a plain function declaration or an explicitly typed const); otherwise the compiler does not use it for control flow.
  • Assertion functions (asserts x is T) throw when the condition fails and narrow afterwards.
  • Custom errors. Set name, add typed fields, and use instanceof in handlers. Mark rarely caught errors in documentation.
  • Throw expressions are not part of JavaScript yet, so const x = y ?? throw new Error() is a syntax error; use a helper such as fail() instead.
  • Expected failures are better returned as values; see Result and Either types.
  • Async. Throwing inside an async function rejects the returned promise rather than throwing synchronously.