|
| 1 | +--- |
| 2 | +title: preserve-caught-error |
| 3 | +rule_type: suggestion |
| 4 | +further_reading: |
| 5 | +- https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause |
| 6 | +- https://nodejs.org/api/errors.html#errorcause |
| 7 | +- https://github.com/tc39/proposal-error-cause/blob/main/README.md |
| 8 | +- https://dev.to/amnish04/never-lose-valuable-error-context-in-javascript-3aco |
| 9 | +- https://github.com/microsoft/TypeScript/blob/main/src/lib/es2022.error.d.ts |
| 10 | +--- |
| 11 | + |
| 12 | +JavaScript developers often re-throw errors in `catch` blocks to add context but forget to preserve the original error, resulting in lost debugging information. |
| 13 | + |
| 14 | +Using the `cause` option when throwing new errors helps retain the original error and maintain complete error chains, which improves debuggability and traceability. |
| 15 | + |
| 16 | +```js |
| 17 | +try { |
| 18 | + await fetch("https://xyz.com/resource"); |
| 19 | +} catch(error) { |
| 20 | + // Throw a more specific error without losing original context |
| 21 | + throw new Error("Failed to fetch resource", { |
| 22 | + cause: error |
| 23 | + }); |
| 24 | +} |
| 25 | +``` |
| 26 | + |
| 27 | +## Rule Details |
| 28 | + |
| 29 | +This rule enforces the use of the `cause` property when throwing a new error inside a `catch` block. |
| 30 | + |
| 31 | +Checks for all built-in `error types` that support passing a `cause`. |
| 32 | + |
| 33 | +Examples of **incorrect** code for this rule: |
| 34 | + |
| 35 | +::: incorrect |
| 36 | + |
| 37 | +```js |
| 38 | +/* eslint preserve-caught-error: "error" */ |
| 39 | + |
| 40 | +// Not using the `cause` option |
| 41 | +try { |
| 42 | + // ... |
| 43 | +} catch (error) { |
| 44 | + throw new Error("Something went wrong: " + error.message); |
| 45 | +} |
| 46 | + |
| 47 | +// Throwing a new Error with unrelated cause |
| 48 | +try { |
| 49 | + doSomething(); |
| 50 | +} catch (err) { |
| 51 | + const unrelated = new Error("other"); |
| 52 | + throw new Error("Something failed", { cause: unrelated }); |
| 53 | +} |
| 54 | + |
| 55 | +// Caught error is being lost partially due to destructuring |
| 56 | +try { |
| 57 | + doSomething(); |
| 58 | +} catch ({ message, ...rest }) { |
| 59 | + throw new Error(message); |
| 60 | +} |
| 61 | + |
| 62 | +// Cause error is being shadowed by a closer scoped redeclaration. |
| 63 | +try { |
| 64 | + doSomething(); |
| 65 | +} catch (error) { |
| 66 | + if (whatever) { |
| 67 | + const error = anotherError; // This declaration is the problem. |
| 68 | + throw new Error("Something went wrong", { cause: error }); |
| 69 | + } |
| 70 | +} |
| 71 | +``` |
| 72 | + |
| 73 | +::: |
| 74 | + |
| 75 | +Examples of **correct** code for this rule: |
| 76 | + |
| 77 | +::: correct |
| 78 | + |
| 79 | +```js |
| 80 | +/* eslint preserve-caught-error: "error" */ |
| 81 | + |
| 82 | +try { |
| 83 | + // ... |
| 84 | +} catch (error) { |
| 85 | + throw new Error("Something went wrong", { cause: error }); |
| 86 | +} |
| 87 | + |
| 88 | +// When the thrown error is not directly related to the caught error. |
| 89 | +try { |
| 90 | +} catch (error) { |
| 91 | + foo = { |
| 92 | + bar() { |
| 93 | + // This throw is not directly related to the caught error. |
| 94 | + throw new Error("Something went wrong"); |
| 95 | + } |
| 96 | + }; |
| 97 | +} |
| 98 | + |
| 99 | +// No throw inside catch |
| 100 | +try { |
| 101 | + doSomething(); |
| 102 | +} catch (e) { |
| 103 | + console.error(e); |
| 104 | +} |
| 105 | + |
| 106 | +// Ignoring the caught error at the parameter level |
| 107 | +// This is valid by default, but this behavior can be changed |
| 108 | +// by using the `requireCatchParameter` option discussed below. |
| 109 | +try { |
| 110 | + doSomething(); |
| 111 | +} catch { |
| 112 | + throw new TypeError("Something went wrong"); |
| 113 | +} |
| 114 | +``` |
| 115 | + |
| 116 | +::: |
| 117 | + |
| 118 | +## Options |
| 119 | + |
| 120 | +This rule takes a single option — an object with the following optional property: |
| 121 | + |
| 122 | +- `requireCatchParameter`: Requires the catch blocks to always have the caught error parameter when set to `true`. By default, this is `false`. |
| 123 | + |
| 124 | +### requireCatchParameter |
| 125 | + |
| 126 | +Enabling this option mandates for all the catch blocks to have a caught error parameter. This makes sure that the caught error is not discarded at the parameter level. |
| 127 | + |
| 128 | +```js |
| 129 | +"preserve-caught-error": ["error", { |
| 130 | + "requireCatchParameter": true |
| 131 | +}] |
| 132 | +``` |
| 133 | + |
| 134 | +Example of **incorrect** code for the `{ "requireCatchParameter": true }` option: |
| 135 | + |
| 136 | +::: incorrect |
| 137 | + |
| 138 | +```js |
| 139 | +/* eslint preserve-caught-error: ["error", { "requireCatchParameter": true }] */ |
| 140 | + |
| 141 | +try { |
| 142 | + doSomething(); |
| 143 | +} catch { // Can't discard the error ❌ |
| 144 | + throw new Error("Something went wrong"); |
| 145 | +} |
| 146 | +``` |
| 147 | + |
| 148 | +::: |
| 149 | + |
| 150 | +Example of **correct** code for the `{ "requireCatchParameter": true }` option: |
| 151 | + |
| 152 | +::: correct |
| 153 | + |
| 154 | +```js |
| 155 | +/* eslint preserve-caught-error: ["error", { "requireCatchParameter": true }] */ |
| 156 | + |
| 157 | +try { |
| 158 | + doSomething(); |
| 159 | +} catch(error) { // Error is being referenced ✅ |
| 160 | + // Handling and re-throw logic |
| 161 | +} |
| 162 | +``` |
| 163 | + |
| 164 | +::: |
| 165 | + |
| 166 | +## When Not To Use It |
| 167 | + |
| 168 | +You might not want to enable this rule if: |
| 169 | + |
| 170 | +- You follow a custom error-handling approach where the original error is intentionally omitted from re-thrown errors (e.g., to avoid exposing internal details or to log the original error separately). |
| 171 | + |
| 172 | +- You use a third-party or internal error-handling library that preserves error context using non-standard properties (e.g., [verror](https://www.npmjs.com/package/verror)) instead of the cause option. |
| 173 | + |
| 174 | +- (In rare cases) you are targeting legacy environments where the cause option in `Error` constructors is not supported. |
0 commit comments