diff --git a/docs/src/rules/no-unused-vars.md b/docs/src/rules/no-unused-vars.md
index bca9c06d791..d924f02d657 100644
--- a/docs/src/rules/no-unused-vars.md
+++ b/docs/src/rules/no-unused-vars.md
@@ -132,12 +132,12 @@ var global_var = 42;
This rule takes one argument which can be a string or an object. The string settings are the same as those of the `vars` property (explained below).
-By default this rule is enabled with `all` option for variables and `after-used` for arguments.
+By default this rule is enabled with `all` option for caught errors and variables, and `after-used` for arguments.
```json
{
"rules": {
- "no-unused-vars": ["error", { "vars": "all", "args": "after-used", "caughtErrors": "none", "ignoreRestSiblings": false }]
+ "no-unused-vars": ["error", { "vars": "all", "args": "after-used", "caughtErrors": "all", "ignoreRestSiblings": false }]
}
}
```
@@ -283,20 +283,22 @@ The `caughtErrors` option is used for `catch` block arguments validation.
It has two settings:
-* `none` - do not check error objects. This is the default setting.
-* `all` - all named arguments must be used.
+* `all` - all named arguments must be used. This is the default setting.
+* `none` - do not check error objects.
-#### caughtErrors: none
+#### caughtErrors: all
-Not specifying this rule is equivalent of assigning it to `none`.
+Not specifying this option is equivalent of assigning it to `all`.
-Examples of **correct** code for the `{ "caughtErrors": "none" }` option:
+Examples of **incorrect** code for the `{ "caughtErrors": "all" }` option:
-::: correct
+::: incorrect
```js
-/*eslint no-unused-vars: ["error", { "caughtErrors": "none" }]*/
+/*eslint no-unused-vars: ["error", { "caughtErrors": "all" }]*/
+// 1 error
+// "err" is defined but never used
try {
//...
} catch (err) {
@@ -306,17 +308,15 @@ try {
:::
-#### caughtErrors: all
+#### caughtErrors: none
-Examples of **incorrect** code for the `{ "caughtErrors": "all" }` option:
+Examples of **correct** code for the `{ "caughtErrors": "none" }` option:
-::: incorrect
+::: correct
```js
-/*eslint no-unused-vars: ["error", { "caughtErrors": "all" }]*/
+/*eslint no-unused-vars: ["error", { "caughtErrors": "none" }]*/
-// 1 error
-// "err" is defined but never used
try {
//...
} catch (err) {
diff --git a/docs/src/use/migrate-to-9.0.0.md b/docs/src/use/migrate-to-9.0.0.md
index 7e0616c0d1a..7f45ddf2492 100644
--- a/docs/src/use/migrate-to-9.0.0.md
+++ b/docs/src/use/migrate-to-9.0.0.md
@@ -33,6 +33,7 @@ The lists below are ordered roughly by the number of users each change is expect
* [`no-restricted-imports` now accepts multiple config entries with the same `name`](#no-restricted-imports)
* [`"eslint:recommended"` and `"eslint:all"` strings no longer accepted in flat config](#string-config)
* [`no-inner-declarations` has a new default behavior with a new option](#no-inner-declarations)
+* [`no-unused-vars` now defaults `caughtErrors` to `"all"`](#no-unused-vars)
### Breaking changes for plugin developers
@@ -362,6 +363,33 @@ if (test) {
**Related issue(s):** [#15576](https://github.com/eslint/eslint/issues/15576)
+## `no-unused-vars` now defaults `caughtErrors` to `"all"`
+
+ESLint v9.0.0 changes the default value for the `no-unused-vars` rule's `caughtErrors` option.
+Previously it defaulted to `"none"` to never check whether caught errors were used.
+It now defaults to `"all"` to check caught errors for being used.
+
+```js
+/*eslint no-unused-vars: "error"*/
+try {}
+catch (error) {
+ // 'error' is defined but never used
+}
+```
+
+**To address:** If you want to allow unused caught errors, such as when writing code that will be directly run in an environment that does not support ES2019 optional catch bindings, set the `caughtErrors` option to `"none"`.
+Otherwise, delete the unused caught errors.
+
+```js
+/*eslint no-unused-vars: "error"*/
+try {}
+catch {
+ // no error
+}
+```
+
+**Related issue(s):** [#17974](https://github.com/eslint/eslint/issues/17974)
+
## Removed multiple `context` methods
ESLint v9.0.0 removes multiple deprecated methods from the `context` object and moves them onto the `SourceCode` object:
diff --git a/lib/rules/no-unused-vars.js b/lib/rules/no-unused-vars.js
index 5ccbff7617b..74a664089ed 100644
--- a/lib/rules/no-unused-vars.js
+++ b/lib/rules/no-unused-vars.js
@@ -92,7 +92,7 @@ module.exports = {
vars: "all",
args: "after-used",
ignoreRestSiblings: false,
- caughtErrors: "none"
+ caughtErrors: "all"
};
const firstOption = context.options[0];
diff --git a/tests/lib/rules/no-unused-vars.js b/tests/lib/rules/no-unused-vars.js
index 01118f2e48e..0d8e7c33b89 100644
--- a/tests/lib/rules/no-unused-vars.js
+++ b/tests/lib/rules/no-unused-vars.js
@@ -113,7 +113,6 @@ ruleTester.run("no-unused-vars", rule, {
"myFunc(function foo(){}.toString())",
"function foo(first, second) {\ndoStuff(function() {\nconsole.log(second);});}; foo()",
"(function() { var doSomething = function doSomething() {}; doSomething() }())",
- "try {} catch(e) {}",
"/*global a */ a;",
{ code: "var a=10; (function() { alert(a); })();", options: [{ vars: "all" }] },
{ code: "function g(bar, baz) { return baz; }; g();", options: [{ vars: "all" }] },
@@ -283,13 +282,17 @@ ruleTester.run("no-unused-vars", rule, {
{ code: "let x = 0; foo = (0, x = x + 1);", languageOptions: { ecmaVersion: 6 } },
// caughtErrors
+ {
+ code: "try{}catch(err){}",
+ options: [{ caughtErrors: "none" }]
+ },
{
code: "try{}catch(err){console.error(err);}",
options: [{ caughtErrors: "all" }]
},
{
- code: "try{}catch(err){}",
- options: [{ caughtErrors: "none" }]
+ code: "try{}catch(ignoreErr){}",
+ options: [{ caughtErrorsIgnorePattern: "^ignore" }]
},
{
code: "try{}catch(ignoreErr){}",
@@ -299,7 +302,7 @@ ruleTester.run("no-unused-vars", rule, {
// caughtErrors with other combinations
{
code: "try{}catch(err){}",
- options: [{ vars: "all", args: "all" }]
+ options: [{ caughtErrors: "none", vars: "all", args: "all" }]
},
// Using object rest for variable omission
@@ -1122,6 +1125,10 @@ ruleTester.run("no-unused-vars", rule, {
},
// caughtErrors
+ {
+ code: "try{}catch(err){};",
+ errors: [definedError("err")]
+ },
{
code: "try{}catch(err){};",
options: [{ caughtErrors: "all" }],