Troubleshooting ESLint

Solutions to common ESLint errors, configuration issues, performance problems, and integration challenges

Troubleshooting ESLint

Quick solutions to common ESLint problems, errors, and configuration issues.

Use Ctrl+F (or Cmd+F) to search for your specific error message on this page.

---

Installation Issues

Error: Cannot find module 'eslint'

Cause: ESLint is not installed or not in your PATH.

Solution:

# Install ESLint locally
npm install eslint --save-dev

# Or globally (not recommended)
npm install -g eslint

# Verify installation
npx eslint --version

Always install ESLint as a dev dependency in your project, not globally. This ensures version consistency across your team.

Error: peer dependency warning for eslint

Cause: A plugin requires a different ESLint version than you have installed.

Solution:

# Check ESLint version
npm list eslint

# Update ESLint to match plugin requirements
npm install eslint@^10.0.0 --save-dev

# Or update the plugin
npm install eslint-plugin-react@latest --save-dev

For pnpm users:

# Create .npmrc with:
auto-install-peers=true
node-linker=hoisted

Error: Cannot find module '@eslint/js'

Cause: The @eslint/js package is not installed.

Solution:

npm install @eslint/js --save-dev

In your config:

import js from "@eslint/js";

export default [
  js.configs.recommended,
  // your config
];

---

Configuration Issues

Error: ESLint configuration not found

Cause: ESLint v10 cannot find eslint.config.js.

Solutions:

1. Create config file:

npm init @eslint/config@latest

2. Ensure correct filename:

• ✅ eslint.config.js
• ✅ eslint.config.mjs
• ✅ eslint.config.cjs
• ❌ .eslintrc (no longer supported in v10)
• ❌ .eslintrc.json (no longer supported in v10)

3. Verify file location:

# Config should be in project root or parent directories
ls -la eslint.config.js

4. Specify config explicitly:

npx eslint --config ./path/to/eslint.config.js .

Error: /* eslint-env */ comments are no longer supported

Cause: You’re using /* eslint-env */ comments, which are not supported in ESLint v10.

Solution:

Before (ESLint v8):

/* eslint-env node, es6 */
const fs = require('fs');

After (ESLint v10):

// Remove the comment from your file
const fs = require('fs');

In eslint.config.js:

import globals from "globals";

export default [
  {
    languageOptions: {
      globals: {
        ...globals.node,
        ...globals.es2021
      }
    }
  }
];

Error: Invalid configuration object

Cause: Your eslint.config.js has a syntax or structure error.

Common mistakes:

1. Not exporting an array:

// ❌ Wrong
export default {
  rules: { "no-console": "error" }
};

// ✅ Correct
export default [
  {
    rules: { "no-console": "error" }
  }
];

2. Mixing old and new config formats:

// ❌ Wrong (old format in flat config)
export default [
  {
    extends: ["eslint:recommended"] // No 'extends' in flat config
  }
];

// ✅ Correct
import js from "@eslint/js";
export default [
  js.configs.recommended
];

Debug your config:

node eslint.config.js

Rules not applying to my files

Cause: File patterns don’t match or files are ignored.

Solutions:

1. Check file patterns:

export default [
  {
    files: ["**/*.js", "**/*.jsx"], // Make sure this matches your files
    rules: {
      "no-console": "error"
    }
  }
];

2. Check ignored files:

export default [
  {
    ignores: ["dist/**", "build/**", "node_modules/**"]
  }
];

3. Debug config for a specific file:

npx eslint --print-config src/app.js

4. Verify file is being linted:

npx eslint src/app.js --debug

Error: Failed to load parser

Cause: Custom parser (like @typescript-eslint/parser) is not installed or configured incorrectly.

Solution:

1. Install parser:

npm install @typescript-eslint/parser --save-dev

2. Configure correctly:

import tsParser from "@typescript-eslint/parser";

export default [
  {
    files: ["**/*.ts"],
    languageOptions: {
      parser: tsParser, // Not as a string
      parserOptions: {
        project: "./tsconfig.json"
      }
    }
  }
];

---

Runtime Errors

Error: 'context.getFilename' is not a function

Cause: Using deprecated context methods removed in ESLint v10.

Solution:

Before:

module.exports = {
  create(context) {
    const filename = context.getFilename();
    const sourceCode = context.getSourceCode();
  }
};

After:

module.exports = {
  create(context) {
    const filename = context.filename;
    const sourceCode = context.sourceCode;
  }
};

Full migration table:

Removed	Replacement
context.getCwd()	context.cwd
context.getFilename()	context.filename
context.getPhysicalFilename()	context.physicalFilename
context.getSourceCode()	context.sourceCode

Error: Unexpected token 'export'

Cause: Your config file uses ESM syntax but Node.js is treating it as CommonJS.

Solutions:

1. Rename to .mjs:

mv eslint.config.js eslint.config.mjs

2. Add “type”: “module” to package.json:

{
  "type": "module"
}

3. Or use CommonJS:

// eslint.config.cjs
const js = require("@eslint/js");

module.exports = [
  js.configs.recommended
];

Error: Parsing error: Unexpected token

Cause: Parser cannot understand your code syntax.

Solutions:

For TypeScript:

npm install @typescript-eslint/parser --save-dev

import tsParser from "@typescript-eslint/parser";

export default [
  {
    files: ["**/*.ts", "**/*.tsx"],
    languageOptions: {
      parser: tsParser
    }
  }
];

For JSX:

export default [
  {
    files: ["**/*.jsx", "**/*.tsx"],
    languageOptions: {
      parserOptions: {
        ecmaFeatures: {
          jsx: true
        }
      }
    }
  }
];

For modern JavaScript:

export default [
  {
    languageOptions: {
      ecmaVersion: "latest",
      sourceType: "module"
    }
  }
];

Error: Failed to load plugin

Cause: Plugin not installed or imported incorrectly.

Solution:

1. Install plugin:

npm install eslint-plugin-react --save-dev

2. Import correctly:

import react from "eslint-plugin-react";

export default [
  {
    plugins: {
      react // Not as a string
    },
    rules: {
      "react/prop-types": "error"
    }
  }
];

---

Performance Issues

ESLint is very slow

Causes & Solutions:

1. Enable caching:

npx eslint --cache .

2. Limit file scope:

export default [
  {
    files: ["src/**/*.js"],
    ignores: [
      "dist/**",
      "build/**",
      "node_modules/**",
      "**/*.min.js"
    ]
  }
];

3. Disable expensive rules:

export default [
  {
    rules: {
      // These require type checking (slow)
      "@typescript-eslint/no-floating-promises": "off",
      "@typescript-eslint/no-misused-promises": "off"
    }
  }
];

4. Use faster glob patterns:

# Slow
npx eslint "**/*.js"

# Faster
npx eslint src/

5. Parallelize in CI:

# Install
npm install eslint-parallel --save-dev

# Run
npx eslint-parallel 'src/**/*.js'

Out of memory errors

Cause: Large codebase or complex rules exceeding Node.js memory limit.

Solutions:

1. Increase Node.js memory:

NODE_OPTIONS="--max-old-space-size=4096" npx eslint .

2. Lint in batches:

npx eslint src/componentA/
npx eslint src/componentB/

3. Reduce file scope:

export default [
  {
    ignores: ["**/*.spec.js", "**/*.test.js"]
  }
];

Linting hangs or times out

Cause: Infinite loop in a rule or extremely complex file.

Solutions:

1. Identify problematic file:

npx eslint --debug . 2>&1 | grep "Linting"

2. Skip specific file:

export default [
  {
    ignores: ["src/problematic-file.js"]
  }
];

3. Update plugins:

npm update eslint-plugin-*

---

Editor Integration Issues

VS Code: ESLint not working

Solutions:

1. Install ESLint extension:

• Install “ESLint” by Microsoft from VS Code marketplace

2. Check output panel:

• View → Output → Select “ESLint” from dropdown
• Look for error messages

3. Restart ESLint server:

• Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
• Type “ESLint: Restart ESLint Server”

4. Configure settings.json:

{
  "eslint.experimental.useFlatConfig": true,
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ]
}

5. Check workspace settings:

{
  "eslint.workingDirectories": [
    { "mode": "auto" }
  ]
}

WebStorm/IntelliJ: ESLint not working

Solutions:

1. Enable ESLint:

• Settings → Languages & Frameworks → JavaScript → Code Quality Tools → ESLint
• Check “Automatic ESLint configuration”

2. Verify Node.js interpreter:

• Settings → Languages & Frameworks → Node.js
• Ensure correct Node.js version (20.19+)

3. Specify config file:

• ESLint settings → Configuration file
• Point to eslint.config.js

4. Clear caches:

• File → Invalidate Caches / Restart

Conflicting Prettier/ESLint formatting

Cause: Both tools trying to format code differently.

Solution:

1. Use Prettier for formatting, ESLint for logic:

npm install prettier eslint-config-prettier --save-dev

2. Disable ESLint formatting rules:

import eslintConfigPrettier from "eslint-config-prettier";

export default [
  // Your config
  eslintConfigPrettier // Must be last
];

3. Run separately:

{
  "scripts": {
    "lint": "eslint .",
    "format": "prettier --write ."
  }
}

---

CI/CD Issues

ESLint passes locally but fails in CI

Causes & Solutions:

1. Different Node.js versions:

# .github/workflows/lint.yml
- uses: actions/setup-node@v4
  with:
    node-version: '20.19' # Match your local version

2. Missing dependencies:

- run: npm ci # Use 'ci' not 'install'
- run: npm run lint

3. Cached node_modules:

- uses: actions/cache@v3
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

4. Platform-specific line endings:

export default [
  {
    rules: {
      "linebreak-style": ["error", "unix"]
    }
  }
];

Exit code 0 even with errors

Cause: Errors are configured as warnings.

Solutions:

1. Use —max-warnings 0:

npx eslint --max-warnings 0 .

2. Change warnings to errors:

export default [
  {
    rules: {
      "no-console": "error" // not "warn"
    }
  }
];

---

Migration Issues

Upgrading from v9 to v10

See the complete Migration Guide for step-by-step instructions.

Quick checklist:

• ✅ Node.js v20.19.0+
• ✅ Remove v10_config_lookup_from_file flag
• ✅ Remove .eslintrc files
• ✅ Remove /* eslint-env */ comments
• ✅ Update context methods in custom rules
• ✅ Update SourceCode methods

Converting .eslintrc to flat config

Old format (.eslintrc.json):

{
  "extends": ["eslint:recommended"],
  "env": { "node": true },
  "rules": { "no-console": "off" }
}

New format (eslint.config.js):

import js from "@eslint/js";
import globals from "globals";

export default [
  js.configs.recommended,
  {
    languageOptions: {
      globals: globals.node
    },
    rules: {
      "no-console": "off"
    }
  }
];

Use migration tool:

npx @eslint/migrate-config .eslintrc.json

---

Debugging Commands

Print config for file

npx eslint --print-config src/app.js

npx eslint --debug src/

npx eslint --print-config src/app.js | grep rules -A 100

npx eslint --version

node eslint.config.js

---

Getting Help

GitHub Discussions

Ask questions and get help from the community

Discord Server

Real-time chat with ESLint users and maintainers

Stack Overflow

Search existing questions or ask new ones

Report a Bug

File an issue on GitHub

---

Common Error Messages Reference

Quick reference for frequently encountered errors:

Error Message	Cause	Solution
Configuration not found	No eslint.config.js	Create config file
Failed to load parser	Parser not installed	npm install parser
Failed to load plugin	Plugin not installed	npm install plugin
/* eslint-env */ not supported	Using v8 syntax	Remove comment, use config
context.getFilename is not a function	Deprecated API	Use context.filename
Invalid configuration object	Syntax error in config	Check config syntax
Unexpected token 'export'	ESM/CJS mismatch	Rename to .mjs or add "type": "module"
Parsing error	Parser configuration issue	Configure correct parser

Still stuck? Include these details when asking for help:

• ESLint version (npx eslint --version)
• Node.js version (node --version)
• Package manager (npm/pnpm/yarn)
• Full error message
• Relevant config file
• Example code that triggers the issue