useErrorCause (JavaScript)

Language JavaScript (and super languages)

Summary

Rule available since: v2.3.12
Diagnostic Category: lint/style/useErrorCause
This rule isn’t recommended, so you need to enable it.
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
      "style": {
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/style/useErrorCause ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ The original error is not passed to the new `Error` object.
  
    2 │   // ...
    3 │ } catch (err) {
  > 4 │   throw new Error(err.message);
      │   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    5 │ }
    6 │ 
  
  ℹ Without the original error as its `cause`, the stack trace and context of the first failure are lost. This makes the failure harder to trace.
  
  ℹ Pass the original error in the `cause` option, for example `new Error("message", { cause: error })`.

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

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

  ℹ The original error is discarded because the `catch` clause has no parameter.
  
    2 │     doSomething();
    3 │ } catch {
  > 4 │     throw new Error("Something went wrong");
      │     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    5 │ }
    6 │ 
  
  ℹ Without a parameter, the code cannot access the original error, so its details are lost.
  
  ℹ Add a parameter to the `catch` clause and pass it as the `cause` of the new error.

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

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

  ℹ The error is destructured in the `catch` clause.
  
    1 │ try {
    2 │   // ...
  > 3 │ } catch ({ message }) {
      │          ^^^^^^^^^^^
    4 │   throw new Error(message);
    5 │ }
  
  ℹ Destructuring can lose information from the error object, such as the stack trace. The original error also cannot be passed as the `cause`.
  
  ℹ Catch the error in a single variable, read its properties from that variable, and pass the variable as the `cause`.

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/style/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.
  
  ℹ The `cause` refers to a different value than the caught error, so the original error is still lost.
  
  ℹ Rename the variable that shadows the caught error, or pass the caught error as the `cause`.

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
      "style": {
5
        "useErrorCause": {
6
          "level": "on",
7
          "options": {
8
            "requireCatchParameter": false
9
          }
10
        }
11
      }
12
    }
13
  }
14
}

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/style/useErrorCause ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ The original error is discarded because the `catch` clause has no parameter.
  
    2 │     doSomething();
    3 │ } catch {
  > 4 │     throw new Error("Something went wrong");
      │     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    5 │ }
    6 │ 
  
  ℹ Without a parameter, the code cannot access the original error, so its details are lost.
  
  ℹ Add a parameter to the `catch` clause and pass it as the `cause` of the new error.

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
}