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.
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.
First, identify which versions you're currently using:
# 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
If your TypeScript is recent but typescript-eslint is old, update the ESLint packages:
# 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 --latestImportant: Always update both packages together. Mismatched versions between parser and plugin cause issues:
// 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:
npx eslint .If you're using an old TypeScript version, upgrade to a supported release:
# 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@latestBefore 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:
# 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"Check that all TypeScript-related packages are compatible:
# 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@latestFor monorepos using workspaces:
# 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-mismatchesVerify versions are aligned:
// package.json
{
"devDependencies": {
"typescript": "^5.6.2",
"@typescript-eslint/eslint-plugin": "^8.46.4",
"@typescript-eslint/parser": "^8.46.4",
"eslint": "^9.0.0"
}
}If your setup works fine and you want to silence the warning, configure ESLint:
In .eslintrc.js:
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:
{
"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
If version conflicts persist, clean your dependency tree:
# 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 multipleFor stubborn issues, check for global TypeScript installations:
# 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 --versionAfter reinstalling, test ESLint:
npx eslint --version
npx eslint . --debug 2>&1 | grep -i typescript### 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:
# 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:
// .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:
// 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:
npm ls typescript --allUsing pnpm:
# pnpm-workspace.yaml
packages:
- 'packages/*'
# .npmrc
shamefully-hoist=true # Helps avoid version conflictsUsing Lerna or Nx:
# 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:
// 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:
# 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:
# 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:
# 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:
{
"overrides": {
"typescript": "5.6.2"
}
}This forces all dependencies to use the same TypeScript version, even if they specify different ranges.
Function expression requires a return type
Function expression requires a return type
Value of type 'string | undefined' is not iterable
How to fix "Value is not iterable" in TypeScript
Type 'undefined' is not assignable to type 'string'
How to fix "Type undefined is not assignable to type string" in TypeScript
Type narrowing from typeof check produces 'never'
How to fix "Type narrowing produces never" in TypeScript
Type parameter 'T' has conflicting constraints
How to fix "Type parameter has conflicting constraints" in TypeScript