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.
function fail(message: string): never { throw new Error(message); }
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.
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
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
throwsannotation. - A function declared to return
neverwhose end is reachable is error TS2534 ("A function returning 'never' cannot have a reachable end point"). - Unreachable code after
throwis reported only whenallowUnreachableCodeisfalse(error TS7027); otherwise editors just grey it out. - A bare
throw;is a syntax error. To rethrow, writethrow err;insidecatch.
Usage notes
- Throw
Errorobjects. They carrymessage,nameandstack. Throwing strings loses the stack and confusesinstanceofchecks. - Narrowing helpers. A function returning
neveris treated as a terminating call only when it is declared with an explicitneverreturn type annotation (a plain function declaration or an explicitly typedconst); 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 useinstanceofin 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 asfail()instead. - Expected failures are better returned as values; see Result and Either types.
- Async. Throwing inside an
asyncfunction rejects the returned promise rather than throwing synchronously.