useErrorCause

JavaScript (and super languages)

Summary

Diagnostic Category: lint/nursery/useErrorCause
This rule doesn’t have a fix.
The default severity of this rule is information.
Sources:
- Same as preserve-caught-error

How to configure

1
{
2
  "linter": {
3
    "rules": {
4
      "nursery": {
5
        "useErrorCause": "error"
6
      }
7
    }
8
  }
9
}

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

1
try {
2
  // ...
3
} catch (err) {
4
  throw new Error(err.message);
5
}

code-block.js:4:3 lint/nursery/useErrorCause ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ 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 https://biomejs.dev/linter/#nursery for more information.

1
try {
2
    doSomething();
3
} catch {
4
    throw new Error("Something went wrong");
5
}

code-block.js:4:5 lint/nursery/useErrorCause ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ 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 https://biomejs.dev/linter/#nursery for more information.

1
try {
2
  // ...
3
} catch ({ message }) {
4
  throw new Error(message);
5
}

code-block.js:3:10 lint/nursery/useErrorCause ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ 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 https://biomejs.dev/linter/#nursery for more information.

Cause error is being shadowed by a closer scoped redeclaration.

1
try {
2
    doSomething();
3
} catch (error) {
4
    if (whatever) {
5
        const error = anotherError; // This declaration shadows the caught error.
6
        throw new Error("Something went wrong", { cause: error });
7
    }
8
}

code-block.js:6:58 lint/nursery/useErrorCause ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ 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 https://biomejs.dev/linter/#nursery for more information.

Valid

1
try {
2
  // ...
3
} catch (err) {
4
  throw new Error("Something went wrong", { cause: err });
5
}
6

7
try {
8
    throw "Not a rethrow, so it's ignored when nested";
9
} catch (err) {
10
    const fn = () => {
11
        throw new Error("New unrelated error");
12
    }
13
    fn();
14
}

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

1
{
2
  "linter": {
3
    "rules": {
4
      "nursery": {
5
        "useErrorCause": {
6
          "options": {
7
            "requireCatchParameter": false
8
          }
9
        }
10
      }
11
    }
12
  }
13
}

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

1
try {
2
    doSomething();
3
} catch {
4
    throw new Error("Something went wrong");
5
}

code-block.js:4:5 lint/nursery/useErrorCause ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ 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 https://biomejs.dev/linter/#nursery for more information.

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

1
try {
2
    doSomething();
3
} catch {
4
    throw new Error("Something went wrong");
5
}