@@ -191,13 +191,16 @@ provide a text description of the error. |
191 | 191 | All errors generated by Node.js, including all system and JavaScript errors, |
192 | 192 | will either be instances of, or inherit from, the `Error` class. |
193 | 193 |
|
194 | | -### `new Error(message)` |
| 194 | +### `new Error(message[, options])` |
195 | 195 |
|
196 | 196 | * `message` {string} |
| 197 | +* `options` {Object} |
| 198 | + * `cause` {any} The error that caused the newly created error. |
197 | 199 |
|
198 | 200 | Creates a new `Error` object and sets the `error.message` property to the |
199 | 201 | provided text message. If an object is passed as `message`, the text message |
200 | | -is generated by calling `message.toString()`. The `error.stack` property will |
| 202 | +is generated by calling `String(message)`. If the `cause` option is provided, |
| 203 | +it is assigned to the `error.cause` property. The `error.stack` property will |
201 | 204 | represent the point in the code at which `new Error()` was called. Stack traces |
202 | 205 | are dependent on [V8's stack trace API][]. Stack traces extend only to either |
203 | 206 | (a) the beginning of _synchronous code execution_, or (b) the number of frames |
@@ -253,6 +256,49 @@ will affect any stack trace captured _after_ the value has been changed. |
253 | 256 | If set to a non-number value, or set to a negative number, stack traces will |
254 | 257 | not capture any frames. |
255 | 258 |
|
| 259 | +### `error.cause` |
| 260 | + |
| 261 | +<!-- YAML |
| 262 | +added: v16.9.0 |
| 263 | +--> |
| 264 | + |
| 265 | +* {any} |
| 266 | + |
| 267 | +If present, the `error.cause` property is the underlying cause of the `Error`. |
| 268 | +It is used when catching an error and throwing a new one with a different |
| 269 | +message or code in order to still have access to the original error. |
| 270 | + |
| 271 | +The `error.cause` property is typically set by calling |
| 272 | +`new Error(message, { cause })`. It is not set by the constructor if the |
| 273 | +`cause` option is not provided. |
| 274 | + |
| 275 | +This property allows errors to be chained. When serializing `Error` objects, |
| 276 | +[`util.inspect()`][] recursively serializes `error.cause` if it is set. |
| 277 | + |
| 278 | +```js |
| 279 | +const cause = new Error('The remote HTTP server responded with a 500 status'); |
| 280 | +const symptom = new Error('The message failed to send', { cause }); |
| 281 | + |
| 282 | +console.log(symptom); |
| 283 | +// Prints: |
| 284 | +// Error: The message failed to send |
| 285 | +// at REPL2:1:17 |
| 286 | +// at Script.runInThisContext (node:vm:130:12) |
| 287 | +// ... 7 lines matching cause stack trace ... |
| 288 | +// at [_line] [as _line] (node:internal/readline/interface:886:18) { |
| 289 | +// [cause]: Error: The remote HTTP server responded with a 500 status |
| 290 | +// at REPL1:1:15 |
| 291 | +// at Script.runInThisContext (node:vm:130:12) |
| 292 | +// at REPLServer.defaultEval (node:repl:574:29) |
| 293 | +// at bound (node:domain:426:15) |
| 294 | +// at REPLServer.runBound [as eval] (node:domain:437:12) |
| 295 | +// at REPLServer.onLine (node:repl:902:10) |
| 296 | +// at REPLServer.emit (node:events:549:35) |
| 297 | +// at REPLServer.emit (node:domain:482:12) |
| 298 | +// at [_onLine] [as _onLine] (node:internal/readline/interface:425:12) |
| 299 | +// at [_line] [as _line] (node:internal/readline/interface:886:18) |
| 300 | +``` |
| 301 | + |
256 | 302 | ### `error.code` |
257 | 303 |
|
258 | 304 | * {string} |
@@ -3514,6 +3560,7 @@ The native call from `process.cpuUsage` could not be processed. |
3514 | 3560 | [`subprocess.send()`]: child_process.md#subprocesssendmessage-sendhandle-options-callback |
3515 | 3561 | [`url.parse()`]: url.md#urlparseurlstring-parsequerystring-slashesdenotehost |
3516 | 3562 | [`util.getSystemErrorName(error.errno)`]: util.md#utilgetsystemerrornameerr |
| 3563 | +[`util.inspect()`]: util.md#utilinspectobject-options |
3517 | 3564 | [`util.parseArgs()`]: util.md#utilparseargsconfig |
3518 | 3565 | [`v8.startupSnapshot.setDeserializeMainFunction()`]: v8.md#v8startupsnapshotsetdeserializemainfunctioncallback-data |
3519 | 3566 | [`zlib`]: zlib.md |
|