Troubleshooting & Common Gotchas

Known issues and solutions

Config not loading? Parser errors? Rules don't apply? These are fixable. Most issues come from config syntax, plugin conflicts, or the order of entries in the flat config array.

Troubleshooting checklist

Step-by-step debugging for common issues.

# Issue 1: Config not found
npx eslint --print-config src/app.js | head -20

# Issue 2: Prettier conflicts with ESLint
# Verify eslint-config-prettier is the LAST entry in eslint.config.js

# Issue 3: Rule not applying
npx eslint src/app.js --debug

# Issue 4: Parser error
# Check languageOptions.ecmaVersion / parser matches your code

# Issue 5: Plugin not loaded
npx eslint --print-config src/app.js | grep -A3 plugins

Output:

Use these commands to debug any ESLint issue

Start minimal, add gradually

If issues persist, start with js.configs.recommended only, then add plugins one at a time. This isolates the problem.

Quick check

Quick check: If a rule isn't applying, what should you check first?

• Restart the editor only
• Delete the config and start over
• Use npx eslint --print-config on the file
• Uninstall ESLint