How to fix Invalid TypeScript version for @typescript-eslint rule in TypeScript

TypeScriptINTERMEDIATEMEDIUM

This warning appears when you're using a version of TypeScript that isn't officially supported by typescript-eslint. The fix typically involves updating either TypeScript or typescript-eslint to compatible versions, or suppressing the warning if your setup works correctly.

What this error means

The "Invalid TypeScript version" or "You are currently running a version of TypeScript which is not officially supported by @typescript-eslint/typescript-estree" warning occurs when there's a version mismatch between TypeScript and the typescript-eslint tooling. typescript-eslint mirrors DefinitelyTyped's support window, meaning it only officially supports TypeScript versions less than 2 years old. The warning appears during ESLint execution and indicates that while your code may work fine, the typescript-eslint team doesn't guarantee compatibility and won't accept bug reports for unsupported version combinations. This commonly happens when: 1. **Using an older TypeScript version**: Your project uses TypeScript 4.7 or earlier while typescript-eslint has moved on 2. **Using a bleeding-edge TypeScript version**: You've upgraded to a brand new TypeScript release before typescript-eslint has added official support 3. **Dependency version drift**: Different parts of your toolchain have updated independently, creating mismatches Currently, typescript-eslint supports TypeScript versions >=4.8.4 <6.0.0. The project actively maintains support for the latest stable TypeScript releases, typically adding support within days of a new TypeScript version being released.

How to fix "Invalid TypeScript version for @typescript-eslint rule"

1Check current TypeScript and typescript-eslint versions

First, identify which versions you're currently using:

bash

# Check TypeScript version
npx tsc --version

# Check typescript-eslint versions
npm list typescript @typescript-eslint/parser @typescript-eslint/eslint-plugin

# Or check package.json directly
cat package.json | grep -E "typescript|@typescript-eslint"

Compare your versions against the compatibility matrix:
- TypeScript: >=4.8.4 <6.0.0
- typescript-eslint: Latest is 8.x (supports TypeScript 5.6+ since v8.10.0)
- ESLint: ^8.57.0 || ^9.0.0
- Node.js: ^18.18.0 || ^20.9.0 || >=21.1.0

2Update typescript-eslint to latest version

If your TypeScript is recent but typescript-eslint is old, update the ESLint packages:

bash

# Update both packages together to ensure version compatibility
npm install --save-dev @typescript-eslint/parser@latest @typescript-eslint/eslint-plugin@latest

# Or using yarn
yarn upgrade @typescript-eslint/parser @typescript-eslint/eslint-plugin --latest

# Or using pnpm
pnpm update @typescript-eslint/parser @typescript-eslint/eslint-plugin --latest

Important: Always update both packages together. Mismatched versions between parser and plugin cause issues:

json

// package.json - ensure versions match
{
  "devDependencies": {
    "@typescript-eslint/eslint-plugin": "^8.46.4",
    "@typescript-eslint/parser": "^8.46.4"
  }
}

After updating, restart your IDE and re-run ESLint:

bash

npx eslint .

3Update TypeScript to a supported version

If you're using an old TypeScript version, upgrade to a supported release:

bash

# Update to latest TypeScript 5.x
npm install --save-dev typescript@latest

# Or install a specific version
npm install --save-dev [email protected]

# For yarn
yarn upgrade typescript@latest

# For pnpm
pnpm update typescript@latest

Before upgrading TypeScript, check for breaking changes:
- TypeScript 5.0+ changed some inference rules
- TypeScript 5.x requires different lib settings for some features
- Review [TypeScript release notes](https://devblogs.microsoft.com/typescript/)

After updating TypeScript:

bash

# Clear TypeScript build cache
rm -rf dist/ build/ .tsbuildinfo

# Recompile to check for new errors
npx tsc --noEmit

# Restart TypeScript server in VS Code
# Press Cmd/Ctrl + Shift + P → "TypeScript: Restart TS Server"

4Align all TypeScript-related package versions

Check that all TypeScript-related packages are compatible:

bash

# List all TypeScript-related packages
npm list typescript @types/node ts-node tsx @typescript-eslint/parser @typescript-eslint/eslint-plugin

# Update all together
npm install --save-dev \
  typescript@latest \
  @typescript-eslint/parser@latest \
  @typescript-eslint/eslint-plugin@latest \
  @types/node@latest

For monorepos using workspaces:

bash

# Update in root
npm install --save-dev --workspaces \
  typescript@latest \
  @typescript-eslint/parser@latest \
  @typescript-eslint/eslint-plugin@latest

# Or use syncpack to sync versions across workspace packages
npx syncpack fix-mismatches

Verify versions are aligned:

json

// package.json
{
  "devDependencies": {
    "typescript": "^5.6.2",
    "@typescript-eslint/eslint-plugin": "^8.46.4",
    "@typescript-eslint/parser": "^8.46.4",
    "eslint": "^9.0.0"
  }
}

5Suppress the warning if versions work correctly

If your setup works fine and you want to silence the warning, configure ESLint:

In .eslintrc.js:

javascript

module.exports = {
  parser: "@typescript-eslint/parser",
  parserOptions: {
    ecmaVersion: "latest",
    sourceType: "module",
    project: "./tsconfig.json",
    warnOnUnsupportedTypeScriptVersion: false, // Disable warning
  },
  plugins: ["@typescript-eslint"],
  extends: [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
  ],
};

In .eslintrc.json:

json

{
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaVersion": "latest",
    "sourceType": "module",
    "project": "./tsconfig.json",
    "warnOnUnsupportedTypeScriptVersion": false
  },
  "plugins": ["@typescript-eslint"],
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended"
  ]
}

⚠️ Warning: Suppressing this warning means you're accepting that typescript-eslint may not work correctly with your TypeScript version. Only do this if:
- Your linting rules work as expected
- You're waiting for typescript-eslint to add official support for a new TypeScript version
- You're on an older TypeScript version temporarily and understand the risks

6Clear cache and reinstall dependencies

If version conflicts persist, clean your dependency tree:

bash

# Remove all dependencies and cache
rm -rf node_modules
rm package-lock.json  # or yarn.lock / pnpm-lock.yaml

# Clear npm cache
npm cache clean --force

# Reinstall with exact versions
npm install

# Verify no duplicate TypeScript installations
npm ls typescript
# Should show a single version, not multiple

For stubborn issues, check for global TypeScript installations:

bash

# Check global TypeScript
npm list -g typescript

# If global TypeScript exists and causes issues, uninstall
npm uninstall -g typescript

# Always use project-local TypeScript
npx tsc --version

After reinstalling, test ESLint:

bash

npx eslint --version
npx eslint . --debug 2>&1 | grep -i typescript

Advanced notes

### Version Compatibility Matrix

typescript-eslint follows a rolling support window:

| typescript-eslint | TypeScript Support | ESLint Support | Node.js Support |
|-------------------|-------------------|----------------|-----------------|
| v8.x (current) | >=4.8.4 <6.0.0 | ^8.57.0 \|\| ^9.0.0 | ^18.18.0 \|\| ^20.9.0 \|\| >=21.1.0 |
| v7.x | >=4.7.4 <5.5.0 | ^8.56.0 | ^18.18.0 \|\| >=20.0.0 |
| v6.x | >=4.3.5 <5.3.0 | ^7.0.0 \|\| ^8.0.0 | ^16.0.0 \|\| >=18.0.0 |

The project typically adds support for new TypeScript versions within days of release. Check the [releases page](https://github.com/typescript-eslint/typescript-eslint/releases) for latest compatibility info.

### Why Version Compatibility Matters

typescript-eslint uses typescript-estree to parse TypeScript code. This parser needs to:

1. Understand TypeScript syntax: New TypeScript versions introduce new syntax (satisfies operator, const type parameters, etc.)
2. Handle type system changes: TypeScript's type checker evolves with breaking changes
3. Generate compatible AST: The abstract syntax tree must match both TypeScript and ESLint expectations

When versions mismatch:
- New TypeScript syntax may not parse correctly
- ESLint rules may not understand new type constructs
- Type-aware linting rules may produce false positives/negatives

### Using Pre-Release TypeScript Versions

If you need to use TypeScript beta/rc versions:

bash

# Install TypeScript nightly or beta
npm install --save-dev typescript@next

# Or specific beta
npm install --save-dev [email protected]

Then suppress the warning and monitor typescript-eslint releases for official support:

javascript

// .eslintrc.js
module.exports = {
  parserOptions: {
    warnOnUnsupportedTypeScriptVersion: false,
  },
};

Follow the [typescript-eslint releases](https://github.com/typescript-eslint/typescript-eslint/releases) and upgrade as soon as support is added.

### Monorepo Version Management

In monorepos, ensure consistent versions across all packages:

Using npm workspaces:

json

// package.json (root)
{
  "devDependencies": {
    "typescript": "^5.6.2",
    "@typescript-eslint/parser": "^8.46.4",
    "@typescript-eslint/eslint-plugin": "^8.46.4"
  },
  "workspaces": ["packages/*"]
}

Child packages inherit these versions unless explicitly overridden. Check for duplicates:

bash

npm ls typescript --all

Using pnpm:

yaml

# pnpm-workspace.yaml
packages:
  - 'packages/*'

# .npmrc
shamefully-hoist=true  # Helps avoid version conflicts

Using Lerna or Nx:

bash

# Sync all package versions
npx lerna exec -- npm install typescript@latest @typescript-eslint/parser@latest @typescript-eslint/eslint-plugin@latest

### CI/CD Considerations

In CI environments, pin exact versions to avoid surprises:

json

// package.json - use exact versions in CI
{
  "devDependencies": {
    "typescript": "5.6.2",           // No caret ^
    "@typescript-eslint/parser": "8.46.4",
    "@typescript-eslint/eslint-plugin": "8.46.4"
  }
}

Or use package-lock.json / yarn.lock / pnpm-lock.yaml and commit it:

bash

# In CI, use exact locked versions
npm ci  # Not npm install

### Debugging Version Issues

Use ESLint's debug mode to see what TypeScript version it detects:

bash

# Debug ESLint execution
DEBUG=eslint:* npx eslint .

# Or typescript-eslint specific debug
TSESTREE_SINGLE_RUN=true npx eslint .

# Check TypeScript compiler API version
node -e "console.log(require('typescript').version)"

If multiple TypeScript versions are installed:

bash

# Find all TypeScript installations
find node_modules -name "typescript" -type d

# Check which version ESLint uses
npx eslint --print-config . | grep -A 10 parserOptions

### Future-Proofing Your Setup

To minimize version compatibility issues:

1. Use Dependabot or Renovate: Auto-create PRs when updates are available
2. Set up version constraints: Use overrides or resolutions in package.json
3. Monitor compatibility: Subscribe to typescript-eslint releases on GitHub
4. Test before upgrading: Run full test suite after any TypeScript/ESLint updates
5. Read release notes: Check for breaking changes in both TypeScript and typescript-eslint

Example using npm overrides:

json

{
  "overrides": {
    "typescript": "5.6.2"
  }
}

This forces all dependencies to use the same TypeScript version, even if they specify different ranges.

How to fix Invalid TypeScript version for @typescript-eslint rule in TypeScript

What this error means

Typical symptoms

Common causes

How to fix "Invalid TypeScript version for @typescript-eslint rule"

Advanced notes

Related errors

Official resources & further reading