Skip to content

Commit 1765c24

Browse files
JoshuaKGoldbergnzakas
JoshuaKGoldberg
and
nzakas
authored
docs: add Troubleshooting page (#18181)
* docs: add Troubleshooting page * Add a mention of updating to the latest * Separated into sections * Tweaked plugin uniquely * Tweaked plugin uniquely (2) * Apply suggestions from code review Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com> * no quotes * Fixed up docs links post-merge * One last link fix: configuration-file(-new) * Update docs/src/use/troubleshooting/index.md Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com> --------- Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>
1 parent e80b60c commit 1765c24

7 files changed

Lines changed: 202 additions & 3 deletions

File tree

‎docs/src/use/troubleshooting/couldnt-determine-the-plugin-uniquely.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
title: ESLint couldn't determine the plugin … uniquely
3+
eleventyNavigation:
4+
key: couldn't determine plugin uniquely
5+
parent: troubleshooting
6+
title: ESLint couldn't determine the plugin … uniquely
7+
---
8+
9+
## Symptoms
10+
11+
When using the [legacy ESLint config system](../configure/configuration-files-deprecated), you may see this error running ESLint after installing dependencies:
12+
13+
```plaintext
14+
ESLint couldn't determine the plugin "${pluginId}" uniquely.
15+
16+
- ${filePath} (loaded in "${importerName}")
17+
- ${filePath} (loaded in "${importerName}")
18+
...
19+
20+
Please remove the "plugins" setting from either config or remove either plugin installation.
21+
```
22+
23+
## Cause
24+
25+
ESLint configuration files allow loading in plugins that may include other plugins.
26+
A plugin package might be specified as a dependency of both your package and one or more ESLint plugins.
27+
Legacy ESLint configuration files may use `extends` to include other configurations.
28+
Those configurations may depend on plugins to provide certain functionality in the configuration.
29+
30+
For example, if your config depends on `eslint-plugin-a@2` and `eslint-plugin-b@3`, and you extend `eslint-config-b` that depends on `eslint-plugin-a@1`, then the `eslint-plugin-a` package might have two different versions on disk:
31+
32+
* `node_modules/eslint-plugin-a`
33+
* `node_modules/eslint-plugin-b/node_modules/eslint-plugin-a`
34+
35+
If the legacy ESLint configuration system sees that both plugins exists in multiple places with different versions, it won't know which one to use.
36+
37+
Note that this issue is only present in the legacy eslintrc configurations.
38+
The new ["flat" config system](../configure/configuration-files) has you `import` the dependencies yourself, removing the need for ESLint to attempt to determine their version uniquely.
39+
40+
## Resolution
41+
42+
Common resolutions for this issue include:
43+
44+
* Upgrading all versions of all packages to their latest version
45+
* Running `npm dedupe` or the equivalent package manager command to deduplicate packages, if their version ranges are compatible
46+
* Using `overrides` or the equivalent package manager `package.json` field, to force a specific version of a plugin package
47+
* Note that this may cause bugs in linting if the plugin package had breaking changes between versions
48+
49+
## Resources
50+
51+
For more information, see:
52+
53+
* [Configure Plugins](../configure/plugins) for documentation on how to extend from plugins
54+
* [Create Plugins](../../extend/plugins#configs-in-plugins) for documentation on how to define plugins

‎docs/src/use/troubleshooting/couldnt-find-the-config.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
title: ESLint couldn't find the config … to extend from
3+
eleventyNavigation:
4+
key: couldn't find the config to extend from
5+
parent: troubleshooting
6+
title: ESLint couldn't find the config … to extend from
7+
---
8+
9+
## Symptoms
10+
11+
When using the [legacy ESLint config system](../configure/configuration-files-deprecated), you may see this error running ESLint after installing dependencies:
12+
13+
```plaintext
14+
ESLint couldn't find the config "${configName}" to extend from. Please check that the name of the config is correct.
15+
16+
The config "${configName}" was referenced from the config file in "${importerName}".
17+
```
18+
19+
## Cause
20+
21+
ESLint configuration files specify shareable configs by their package name in the `extends` array.
22+
That package name is passed to the Node.js `require()`, which looks up the package under local `node_modules/` directories.
23+
For example, the following ESLint config will first try to load a module located at `node_modules/eslint-config-yours`:
24+
25+
```js
26+
module.exports = {
27+
extends: ["eslint-config-yours"],
28+
};
29+
```
30+
31+
The error is output when you attempt to extend from a configuration and the package for that configuration is not found in any searched `node_modules/`.
32+
33+
Common reasons for this occurring include:
34+
35+
* Not running `npm install` or the equivalent package manager command
36+
* Mistyping the case-sensitive name of the package and/or configuration
37+
38+
### Config Name Variations
39+
40+
Note that ESLint supports several config name formats:
41+
42+
* The `eslint-config-` config name prefix may be omitted for brevity, e.g. `extends: ["yours"]`
43+
* [`@` npm scoped packages](https://docs.npmjs.com/cli/v10/using-npm/scope) put the `eslint-config-` prefix after the org scope, e.g. `extends: ["@org/yours"]` to load from `@org/eslint-config-yours`
44+
* A `plugin:` prefix indicates a config is loaded from a shared plugin, e.g. `extends: [plugin:yours/recommended]` to load from `eslint-plugin-yours`
45+
46+
## Resolution
47+
48+
Common resolutions for this issue include:
49+
50+
* Upgrading all versions of all packages to their latest version
51+
* Adding the config as a `devDependency` in your `package.json`
52+
* Running `npm install` or the equivalent package manager command
53+
* Checking that the name in your config file matches the name of the config package
54+
55+
## Resources
56+
57+
For more information, see:
58+
59+
* [Legacy ESLint configuration files](../configure/configuration-files-deprecated#using-a-shareable-configuration-package) for documentation on the legacy ESLint configuration format
60+
* [Legacy ESLint configuration files > Using a shareable configuration package](../configure/configuration-files-deprecated#using-a-shareable-configuration-package) for documentation on using shareable configurations
61+
* [Share Configurations](../../extend/shareable-configs) for documentation on how to define standalone shared configs
62+
* [Create Plugins > Configs in Plugins](../../extend/plugins#configs-in-plugins) for documentation on how to define shared configs in plugins

‎docs/src/use/troubleshooting/couldnt-find-the-plugin.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
title: ESLint couldn't find the plugin …
3+
eleventyNavigation:
4+
key: couldn't find the plugin
5+
parent: troubleshooting
6+
title: ESLint couldn't find the plugin …
7+
---
8+
9+
## Symptoms
10+
11+
When using the [legacy ESLint config system](../configure/configuration-files-deprecated), you may see this error running ESLint after installing dependencies:
12+
13+
```plaintext
14+
ESLint couldn't find the plugin "${pluginName}".
15+
16+
(The package "${pluginName}" was not found when loaded as a Node module from the directory "${resolvePluginsRelativeTo}".)
17+
18+
It's likely that the plugin isn't installed correctly. Try reinstalling by running the following:
19+
20+
npm install ${pluginName}@latest --save-dev
21+
22+
The plugin "${pluginName}" was referenced from the config file in "${importerName}".
23+
```
24+
25+
## Cause
26+
27+
[Legacy ESLint configuration files](../configure/configuration-files-deprecated) specify shareable configs by their package name.
28+
That package name is passed to the Node.js `require()`, which looks up the package under local `node_modules/` directories.
29+
For example, the following ESLint config will first try to load a module located at `node_modules/eslint-plugin-yours`:
30+
31+
```js
32+
module.exports = {
33+
extends: ["plugin:eslint-plugin-yours/config-name"],
34+
};
35+
```
36+
37+
If the package is not found in any searched `node_modules/`, ESLint will print the aforementioned error.
38+
39+
Common reasons for this occurring include:
40+
41+
* Not running `npm install` or the equivalent package manager command
42+
* Mistyping the case-sensitive name of the plugin
43+
44+
### Plugin Name Variations
45+
46+
Note that the `eslint-plugin-` plugin name prefix may be omitted for brevity, e.g. `extends: ["yours"]`.
47+
48+
[`@` npm scoped packages](https://docs.npmjs.com/cli/v10/using-npm/scope) put the `eslint-plugin-` prefix after the org scope, e.g. `extends: ["@org/yours"]` to load from `@org/eslint-plugin-yours`.
49+
50+
## Resolution
51+
52+
Common resolutions for this issue include:
53+
54+
* Upgrading all versions of all packages to their latest version
55+
* Adding the plugin as a `devDependency` in your `package.json`
56+
* Running `npm install` or the equivalent package manager command
57+
* Checking that the name in your config file matches the name of the plugin package
58+
59+
## Resources
60+
61+
For more information, see:
62+
63+
* [Legacy ESLint configuration files](../configure/configuration-files-deprecated#using-a-shareable-configuration-package) for documentation on the legacy ESLint configuration format
64+
* [Configure Plugins](../configure/plugins) for documentation on how to extend from plugins
65+
* [Create Plugins](../../extend/plugins#configs-in-plugins) for documentation on how to define plugins

‎docs/src/use/troubleshooting/index.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: Troubleshooting
3+
eleventyNavigation:
4+
key: troubleshooting
5+
title: Troubleshooting
6+
parent: use eslint
7+
order: 8
8+
---
9+
10+
This page serves as a reference for common issues working with ESLint.
11+
12+
* [`ESLint couldn't determine the plugin … uniquely`](./couldnt-determine-the-plugin-uniquely)
13+
* [`ESLint couldn't find the config … to extend from`](./couldnt-find-the-config)
14+
* [`ESLint couldn't find the plugin …`](./couldnt-find-the-plugin)
15+
16+
Issues oftentimes can be resolved by updating the to latest versions of the `eslint` package and any related packages, such as for ESLint shareable configs and plugins.
17+
18+
If you still can't figure out the problem, please stop by <https://eslint.org/chat/help> to chat with the team.

‎messages/plugin-conflict.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ module.exports = function(it) {
1515
1616
Please remove the "plugins" setting from either config or remove either plugin installation.
1717
18-
If you still can't figure out the problem, please stop by https://eslint.org/chat/help to chat with the team.
18+
If you still can't figure out the problem, please see https://eslint.org/docs/latest/use/troubleshooting.
1919
`;
2020

2121
return result;

‎messages/plugin-invalid.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,6 @@ module.exports = function(it) {
1111
1212
"${configName}" was referenced from the config file in "${importerName}".
1313
14-
If you still can't figure out the problem, please stop by https://eslint.org/chat/help to chat with the team.
14+
If you still can't figure out the problem, please see https://eslint.org/docs/latest/use/troubleshooting.
1515
`.trimStart();
1616
};

‎messages/plugin-missing.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,6 @@ It's likely that the plugin isn't installed correctly. Try reinstalling by runni
1414
1515
The plugin "${pluginName}" was referenced from the config file in "${importerName}".
1616
17-
If you still can't figure out the problem, please stop by https://eslint.org/chat/help to chat with the team.
17+
If you still can't figure out the problem, please see https://eslint.org/docs/latest/use/troubleshooting.
1818
`.trimStart();
1919
};

0 commit comments

Comments
 (0)