I spend far too much time fighting configuration issues in my toolchain. Most issues I even encounter frequently. Help me build a troubleshooting checklist. Simply add other possible configuration mistakes in the comments and I will add them to the article.

Start here

Did you run npm install?

Stupid, I know. But I forget to do this quite a lot when coming back to a shared project.

Did you try turning it off and on again?

Sometimes it helps to restart VSCode and I've even had problems that were solved with restarting my computer, though that is rather rare and might also have been related to the TypeScript server.

Did you install ESLint + Plugins + Presets?

Take a look into your eslintrc configuration file and make a list of all plugins and presets. Than make sure, they as well as ESLint itself are in your projects devDependencies.

Is your npm script set up?

Do you have a lint script in your package.json?

  "scripts": {
    "lint": "eslint --ext .js --ignore-path .gitignore ."
  }

Did you tell ESLint, which directory to lint?

I recently encountered a project where the lint script in the package.json was missing the dot at the very end which tells ESLint to start linting in the same directory as the configuration file is in. This was not easily detected, since ESLint didn't throw any warning but just quit silently.

Did you make sure, ESLint is linting the correct file extensions?

In case you're using TypeScript, Vue.js or other non-standard JavaScript files, make sure to tell ESLint about your file extensions by using the --ext flag like so --ext .js,.ts,.vue.

Do you have more .eslintrc configuration files?

Since .eslintrc configuration files automatically extend configuration files in higher directories, this can cause weird issues. Make sure you don't have any additional configuration files anywhere in your project or in the directories above, that you are unaware of. Sometimes, I accidentally scaffold a project in my home directory and forget to delete the hidden .eslintrc.js.

When looking for more .eslintrc files, remember, that they might be invisible to your file explorer. Use ls -a to show hidden files in your terminal.

Additionally, you can stop ESLint from searching further up the directory tree by adding the root option to the .eslintrc in your project root directory:

{
    "root": true
}

Learn more about Configuration Cascading and Hierarchy in the official documentation.

Do you have the ESLint plugin installed and enabled in VSCode?

Maybe you've just set up a new VSCode installation or something's gone wrong syncing your settings. Make sure, the ESLint plugin is installed and also enabled in VSCode.

Did you set up library execution?

The ESLint plugin requires permission to execute the local ESLint installation from your node_modules. Open the command palette (Ctrl / Cmd + Shift + P) and select ESLint: Manage Library Execution to open the dialog for your project and confirm with 'Accept'.

Did you maybe disable the rule you're testing?

Sometimes we mess projects up. Some might use Standard JS, others the AirBnB preset. Some projects disable certain rules. Make sure, you're not testing a rule that isn't even enabled.

Are you having trouble with the TypeScript integration?

Make sure to install the TypeScript plugin and configure it accordingly: https://github.com/typescript-eslint/typescript-eslint

Do you have confusing overrides?

You might have added some overrides (note: not 'overwrites' – another mistake I made once) for test files or similar. Remove them from your config for a minute to see if that changes anything.

Is the ESLint plugin configured as expected?

Open your VSCode preferences and search for ESLint. There's a host of settings, so make sure, they are all set as you want them to.

Most important:

• Validate: Should contain all languages you want to lint
• Node Path
• Run: Wether to run on save or continuously

Also, be aware, that you might have accidentally overwritten these settings for your workspace or even only one project in your workspace. You can access these overwrites from the VSCode settings panel by simply clicking on 'Workspace' or 'Folder' below the search bar.

Nothing is helping? How to find the solution yourself!

Update all ESLint related dependencies

Maybe you've stumbled upon a bug and maaaaybe it has already been fixed? Use npm outdated to find outdated dependencies in your project and just try to update ESLint, your plugins and presets. If you've installed ESlint globally, take care to use the correct installation.

Are your plugins and presets still maintained?

Some plugins or presets might not get any updates. Take a look at their repositories and issue trackers. Maybe someone there is even experiencing the same problems?

Is the message you're seeing even coming from ESLint?

The origin might also be in other tools like TypeScript or Prettier. You can see which tool is generating the message in VSCode at the end of the message in round brackets.

Take a look at the output panel in VSCode

Open the command palette by pressing Ctrl / Cmd + Shift + P and select 'ESLint: Show Output Channel'. If ESLint throws any errors, they should appear here. That's always a good starting point for further debugging.

Try setting up your ESLint config from scratch

Remove everything ESLint related and start from scratch using the eslint --init command that helps you set everything up.

Add your own troubleshooting tips in the comments!

I will add them to the article so whenever you encounter something new, make sure to leave a comment ;)