Diagnosing ESLint no‑unused‑vars False Positives in JavaScript and TypeScript

Recognizable Condition

ESLint reports a variable as unused even though the variable is referenced in the code. Typical patterns that trigger this false positive include:

• Destructuring assignments where the variable appears on the left‑hand side but is used later.
• Optional chaining calls (e.g., obj?.prop) where the variable is part of the chain.
• Type‑only imports in TypeScript (import type { Foo } from './mod') where the imported name is used only in type positions.

Cause/Diagnostic Table

Possible Cause	Why It Leads to a False Positive
ESLint version < 8.0	The no-unused-vars rule did not treat optional chaining as usage.
parserOptions.ecmaVersion set below 2022	Older ECMAScript limits the parser’s understanding of modern syntax.
Missing or misconfigured @typescript-eslint/parser	TypeScript‑specific constructs (type‑only imports, const assertions) are not recognized as usage.
Inline eslint-disable comments suppressing the rule	The rule is turned off for the line or block, hiding both real and false positives.
Using the default ESLint parser with TypeScript files	The parser cannot understand TypeScript syntax, so it treats type‑only references as unused.

Ordered Checks

1. Confirm ESLint version

   # Run in the project root
   npm list eslint
   # or
   yarn list eslint
   

   Expected output: version >= 8.0.0. If lower, upgrade (npm install eslint@latest --save-dev).

2. Verify parser options

   Open .eslintrc.js, .eslintrc.json, or eslint.config.js and ensure:

   {
     "parserOptions": {
       "ecmaVersion": 2022,
       "sourceType": "module"
     }
   }
   

   If missing, add or update the fields.

3. Ensure TypeScript parser and plugin are installed

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

   Then add to config:

   {
     "parser": "@typescript-eslint/parser",
     "plugins": ["@typescript-eslint"],
     "extends": ["plugin:@typescript-eslint/recommended"]
   }
   

4. Check for suppressing comments

   Search the file for eslint-disable or eslint-disable-next-line that mentions no-unused-vars. Remove them if they are not needed.

5. Run debug to see active parser and rules

   # Replace  with the path to the problematic source
   npx eslint --debug  2>&1 | grep -E "(parser|rule:no-unused-vars)"
   

   Look for lines indicating which parser is used and whether no-unused-vars is active.

Fixes Tied to Findings

• Upgrade ESLint – if version < 8.0, run npm install eslint@latest --save-dev.
• Set modern ECMAScript target – ensure parserOptions.ecmaVersion is 2022 or higher.
• Add TypeScript parser – install @typescript-eslint/parser and @typescript-eslint/eslint-plugin, then configure as shown above.
• Remove unnecessary disables – delete inline eslint-disable lines that only silence no-unused-vars.
• Re‑run lint – after changes, execute npx eslint src/**/*.{js,ts} and confirm the warning disappears.

Escalation Criteria

If the warning persists after applying the above fixes:

1. Check for custom no-unused-vars overrides in overrides sections of the config that may reset the rule.
2. Verify that no other plugin (e.g., eslint-plugin-import) is interfering with the rule’s execution.
3. Run npx eslint --print-config to inspect the final resolved configuration for the file.
4. If the issue remains, consider filing a reproduction in the ESLint repository with the exact code snippet and config.

Throughout this process, keep the project under version control so you can revert any configuration changes if new lint errors appear.