File size: 4,179 Bytes
780c9fe |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 |
---
title: throw
slug: Web/JavaScript/Reference/Statements/throw
page-type: javascript-statement
browser-compat: javascript.statements.throw
sidebar: jssidebar
---
The **`throw`** statement throws a user-defined exception. Execution of the current function will stop (the statements after `throw` won't be executed), and control will be passed to the first [`catch`](/en-US/docs/Web/JavaScript/Reference/Statements/try...catch) block in the call stack. If no `catch` block exists among caller functions, the program will terminate.
{{InteractiveExample("JavaScript Demo: throw statement")}}
```js interactive-example
function getRectArea(width, height) {
if (isNaN(width) || isNaN(height)) {
throw new Error("Parameter is not a number!");
}
}
try {
getRectArea(3, "A");
} catch (e) {
console.error(e);
// Expected output: Error: Parameter is not a number!
}
```
## Syntax
```js-nolint
throw expression;
```
- `expression`
- : The expression to throw.
## Description
The `throw` statement is valid in all contexts where statements can be used. Its execution generates an exception that penetrates through the call stack. For more information on error bubbling and handling, see [Control flow and error handling](/en-US/docs/Web/JavaScript/Guide/Control_flow_and_error_handling).
The `throw` keyword can be followed by any kind of expression, for example:
```js
throw error; // Throws a previously defined value (e.g. within a catch block)
throw new Error("Required"); // Throws a new Error object
```
In practice, the exception you throw should _always_ be an {{jsxref("Error")}} object or an instance of an `Error` subclass, such as {{jsxref("RangeError")}}. This is because code that catches the error may expect certain properties, such as {{jsxref("Error/message", "message")}}, to be present on the caught value. For example, web APIs typically throw {{domxref("DOMException")}} instances, which inherit from `Error.prototype`.
### Automatic semicolon insertion
The syntax forbids line terminators between the `throw` keyword and the expression to be thrown.
```js-nolint example-bad
throw
new Error();
```
The code above is transformed by [automatic semicolon insertion (ASI)](/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#automatic_semicolon_insertion) into:
```js-nolint
throw;
new Error();
```
This is invalid code, because unlike {{jsxref("Statements/return", "return")}}, `throw` must be followed by an expression.
To avoid this problem (to prevent ASI), you could use parentheses:
```js-nolint
throw (
new Error()
);
```
## Examples
### Throwing a user-defined error
This example defines a function that throws a {{jsxref("TypeError")}} if the input is not of the expected type.
```js
function isNumeric(x) {
return ["number", "bigint"].includes(typeof x);
}
function sum(...values) {
if (!values.every(isNumeric)) {
throw new TypeError("Can only add numbers");
}
return values.reduce((a, b) => a + b);
}
console.log(sum(1, 2, 3)); // 6
try {
sum("1", "2");
} catch (e) {
console.error(e); // TypeError: Can only add numbers
}
```
### Throwing an existing object
This example calls a callback-based async function, and throws an error if the callback receives an error.
```js
readFile("foo.txt", (err, data) => {
if (err) {
throw err;
}
console.log(data);
});
```
Errors thrown this way are not catchable by the caller and will cause the program to crash unless (a) the `readFile` function itself catches the error, or (b) the program is running in a context that catches top-level errors. You can handle errors more naturally by using the {{jsxref("Promise/Promise", "Promise()")}} constructor.
```js
function readFilePromise(path) {
return new Promise((resolve, reject) => {
readFile(path, (err, data) => {
if (err) {
reject(err);
}
resolve(data);
});
});
}
try {
const data = await readFilePromise("foo.txt");
console.log(data);
} catch (err) {
console.error(err);
}
```
## Specifications
{{Specifications}}
## Browser compatibility
{{Compat}}
## See also
- {{jsxref("Statements/try...catch", "try...catch")}}
- {{jsxref("Error")}}
|