useErrorCause

import { Tabs, TabItem } from '@astrojs/starlight/components';

<Tabs> <TabItem label="JavaScript (and super languages)" icon="seti:javascript"> :::caution This rule is part of the [nursery](/linter/#nursery) group. This means that it is experimental and the behavior can change at any time. ::: ## Summary - Rule available since: `v2.3.12` - Diagnostic Category: [`lint/nursery/useErrorCause`](/reference/diagnostics#diagnostic-category) - This rule doesn't have a fix. - The default severity of this rule is [**information**](/reference/diagnostics#information). - Sources: - Same as [`preserve-caught-error`](https://eslint.org/docs/latest/rules/preserve-caught-error)

How to configure

json

{
	"linter": {
		"rules": {
			"nursery": {
				"useErrorCause": "error"
			}
		}
	}
}

Description

Enforce that new Error() is thrown with the original error as cause.

When catching and rethrowing an error, it's recommended to wrap the original error in a new Error object to preserve the original error's stack trace and context. The original error should be passed as the cause property of the new Error object.

This rule enforces that practice, helping to maintain a clear and traceable error propagation chain, which is crucial for effective debugging.

Examples

Invalid

try {
  // ...
} catch (err) {
  throw new Error(err.message);
}

<pre class="language-text"><code class="language-text">code-block.js:4:3 <a href="https://biomejs.dev/linter/rules/use-error-cause">lint/nursery/useErrorCause</a> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ℹ The original error is not being passed to the new `Error` object.Include the original error in the `cause` property to preserve it. 2 │ // ... 3 │ } catch (err) { > 4 │ throw new Error(err.message); │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5 │ } 6 │ ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit <a href="https://biomejs.dev/linter/#nursery">https://biomejs.dev/linter/#nursery</a> for more information. </code></pre>

try {
    doSomething();
} catch {
    throw new Error("Something went wrong");
}

<pre class="language-text"><code class="language-text">code-block.js:4:5 <a href="https://biomejs.dev/linter/rules/use-error-cause">lint/nursery/useErrorCause</a> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ℹ The original error is being discarded because the `catch` clause doesn't have a parameter.Specify an error object in the `catch` clause to access the original error. 2 │ doSomething(); 3 │ } catch { > 4 │ throw new Error("Something went wrong"); │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5 │ } 6 │ ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit <a href="https://biomejs.dev/linter/#nursery">https://biomejs.dev/linter/#nursery</a> for more information. </code></pre>

try {
  // ...
} catch ({ message }) {
  throw new Error(message);
}

<pre class="language-text"><code class="language-text">code-block.js:3:10 <a href="https://biomejs.dev/linter/rules/use-error-cause">lint/nursery/useErrorCause</a> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ℹ Destructuring the error in a `catch` clause is not recommended, as it can lead to losing important information from the error object, such as the stack trace.Use a single variable to catch the error, and then access its properties. 1 │ try { 2 │ // ... > 3 │ } catch ({ message }) { │ ^^^^^^^^^^^ 4 │ throw new Error(message); 5 │ } ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit <a href="https://biomejs.dev/linter/#nursery">https://biomejs.dev/linter/#nursery</a> for more information. </code></pre>

Cause error is being shadowed by a closer scoped redeclaration.

try {
    doSomething();
} catch (error) {
    if (whatever) {
        const error = anotherError; // This declaration shadows the caught error.
        throw new Error("Something went wrong", { cause: error });
    }
}

<pre class="language-text"><code class="language-text">code-block.js:6:58 <a href="https://biomejs.dev/linter/rules/use-error-cause">lint/nursery/useErrorCause</a> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ℹ The `cause` property is shadowing the original error from the `catch` clause. 4 │ if (whatever) { 5 │ const error = anotherError; // This declaration shadows the caught error. > 6 │ throw new Error("Something went wrong", { cause: error }); │ ^^^^^ 7 │ } 8 │ } ℹ The original error is declared here. 1 │ try { 2 │ doSomething(); > 3 │ } catch (error) { │ ^^^^^ 4 │ if (whatever) { 5 │ const error = anotherError; // This declaration shadows the caught error. ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit <a href="https://biomejs.dev/linter/#nursery">https://biomejs.dev/linter/#nursery</a> for more information. </code></pre>

Valid

try {
  // ...
} catch (err) {
  throw new Error("Something went wrong", { cause: err });
}

try {
    throw "Not a rethrow, so it's ignored when nested";
} catch (err) {
    const fn = () => {
        throw new Error("New unrelated error");
    }
    fn();
}

Options

The following options are available:

`requireCatchParameter`

If true, the rule will report a diagnostic for a throw statement inside an empty catch {} block, recommending that the error be caught in a parameter.

Default: true

json

{
	"linter": {
		"rules": {
			"nursery": {
				"useErrorCause": {
					"options": {
						"requireCatchParameter": false
					}
				}
			}
		}
	}
}

This option is enabled by default, meaning the following code is considered invalid:

try {
    doSomething();
} catch {
    throw new Error("Something went wrong");
}

To disable this check, you would set the option to false:

try {
    doSomething();
} catch {
    throw new Error("Something went wrong");
}

</TabItem> </Tabs>