How to fix @typescript-eslint cannot parse file without TypeScript in TypeScript

TypeScriptINTERMEDIATEMEDIUMUpdated Dec 8, 2025· 113 views

This error occurs when ESLint is configured to use @typescript-eslint/parser with type-aware linting (parserOptions.project), but tries to lint a file that isn't included in your TypeScript configuration. Files must be in your tsconfig.json's include array or you need to adjust ESLint's configuration to exclude them.

Quick fix

Fixes @typescript-eslint cannot parse file without TypeScript

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es2020"
  },
  "include": [
    "src/**/*",
    "*.js",              // Include root-level JS files
    "scripts/**/*.ts",   // Include scripts directory
    "test/**/*.ts"       // Include test files
  ]
}

Add files to tsconfig.json include array
Create tsconfig.eslint.json for ESLint-specific files
Use ESLint overrides to disable type-aware rules for specific files
Add files to .eslintignore

typescript — error

${
  "compilerOptions": {
    "module": "commonjs",
    "target": "es2020"
  },
  "include": [
    "src/**/*",
    "*.js",              // Include root-level JS files
    "scripts/**/*.ts",   // Include scripts directory
    "test/**/*.ts"       // Include test files
  ]
}
@typescript-eslint cannot parse file without TypeScript

What this error means

The "@typescript-eslint cannot parse file without TypeScript" error appears when ESLint attempts to apply type-aware linting rules to a file that isn't part of your TypeScript project. This happens because you've configured parserOptions.project in your ESLint config, which tells @typescript-eslint/parser to use TypeScript's type checker for enhanced linting rules. When parserOptions.project is set, ESLint needs to generate type information for each file using your tsconfig.json. If a file isn't included in that TypeScript configuration (or is explicitly excluded), the parser cannot build the type information and throws this error. This commonly occurs with configuration files (like .eslintrc.js, jest.config.js), build scripts, or files in directories that are intentionally excluded from TypeScript compilation. The error is actually a safety mechanism - it prevents ESLint from making incorrect type-based assumptions about files that TypeScript isn't supposed to process.

Typical symptoms

ESLint fails with message about parsing files without TypeScript
Error mentions 'parserOptions.project' has been set
Linting fails on .js config files (eslintrc.js, jest.config.js, etc.)
Error occurs after enabling type-aware linting rules
Some files lint successfully while others in the same directory fail
VS Code shows ESLint errors on files that aren't TypeScript source code

Common causes

Config files (.eslintrc.js, jest.config.js) aren't in tsconfig.json's include array
Files are in directories excluded by tsconfig.json (like build/, dist/, scripts/)
parserOptions.project is set but the file isn't part of any referenced tsconfig
Using pure JavaScript files in a project configured for TypeScript-only linting
TypeScript module is not installed locally (installed globally instead)
Multiple tsconfig files exist and ESLint is using the wrong one
Test files or tool scripts live outside src/ but aren't in tsconfig.json

How to fix "@typescript-eslint cannot parse file without TypeScript"

1Add files to tsconfig.json include array

If the files should be type-checked, add them to your tsconfig.json:

json

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es2020"
  },
  "include": [
    "src/**/*",
    "*.js",              // Include root-level JS files
    "scripts/**/*.ts",   // Include scripts directory
    "test/**/*.ts"       // Include test files
  ]
}

For projects with config files at root:

json

{
  "include": [
    "src",
    ".eslintrc.js",
    "jest.config.js",
    "*.config.js"
  ]
}

After updating tsconfig.json, restart your IDE's TypeScript server.

2Create tsconfig.eslint.json for ESLint-specific files

Instead of modifying your main tsconfig.json, create a separate config for ESLint:

json

// tsconfig.eslint.json
{
  "extends": "./tsconfig.json",
  "include": [
    "src/**/*",
    "*.js",
    "*.config.js",
    ".eslintrc.js",
    "scripts/**/*",
    "test/**/*"
  ]
}

Then reference it in your ESLint config:

javascript

// .eslintrc.js
module.exports = {
  parser: "@typescript-eslint/parser",
  parserOptions: {
    project: "./tsconfig.eslint.json",
    tsconfigRootDir: __dirname,
  },
  // ... rest of config
};

This approach keeps your TypeScript compilation config separate from your linting config.

3Use ESLint overrides to disable type-aware rules for specific files

Configure ESLint to use different parser settings for JavaScript config files:

javascript

// .eslintrc.js
module.exports = {
  parser: "@typescript-eslint/parser",
  parserOptions: {
    project: "./tsconfig.json",
  },
  overrides: [
    {
      // Disable type-aware linting for JS files
      files: ["*.js", "*.config.js"],
      parserOptions: {
        project: null,  // Disable type checking
      },
      rules: {
        "@typescript-eslint/no-var-requires": "off",
      },
    },
    {
      // Different config for test files
      files: ["**/__tests__/**", "**/*.test.ts"],
      parserOptions: {
        project: "./tsconfig.test.json",
      },
    },
  ],
};

This tells ESLint not to apply type-aware linting to files that aren't TypeScript source code.

4Add files to .eslintignore

If files shouldn't be linted at all, add them to .eslintignore:

plaintext

# .eslintignore
node_modules/
dist/
build/
*.config.js
.eslintrc.js
coverage/
scripts/

Or use ignorePatterns in .eslintrc.js:

javascript

module.exports = {
  ignorePatterns: [
    "dist",
    "build",
    "*.config.js",
    ".eslintrc.js",
    "scripts/**/*",
  ],
  // ... rest of config
};

This completely skips ESLint processing for these files.

5Verify TypeScript is installed locally

Ensure TypeScript is installed as a local dependency, not globally:

bash

# Check if TypeScript is in package.json
cat package.json | grep typescript

# If not installed locally, add it
npm install --save-dev typescript

# Verify version
npx tsc --version

# For @typescript-eslint dependencies
npm install --save-dev @typescript-eslint/parser @typescript-eslint/eslint-plugin

Global TypeScript installations can cause resolution issues with ESLint.

6Use projectService for automatic tsconfig detection (recommended)

Modern @typescript-eslint/parser (v6+) supports projectService for simpler configuration:

javascript

// .eslintrc.js
module.exports = {
  parser: "@typescript-eslint/parser",
  parserOptions: {
    projectService: true,  // Automatically finds nearest tsconfig.json
    tsconfigRootDir: __dirname,
  },
  plugins: ["@typescript-eslint"],
  extends: [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended-type-checked",
  ],
};

This automatically uses the nearest tsconfig.json for each file and is more forgiving with project structure.

For older versions, use project: true:

javascript

parserOptions: {
  project: true,
  tsconfigRootDir: __dirname,
}

Advanced notes

### Understanding parserOptions.project

The parserOptions.project setting enables type-aware linting rules like:
- @typescript-eslint/no-floating-promises
- @typescript-eslint/no-misused-promises
- @typescript-eslint/await-thenable
- @typescript-eslint/no-unnecessary-type-assertion

These rules require TypeScript's type checker to work. Setting project tells ESLint which tsconfig.json to use for type information. However, this comes with a cost: every file ESLint processes must be included in that TypeScript configuration.

Options for parserOptions.project:

javascript

// Single tsconfig
project: "./tsconfig.json"

// Multiple tsconfigs
project: ["./tsconfig.json", "./tsconfig.test.json"]

// Automatic detection (v6+)
project: true

// Automatic with projectService (v6.21.0+, recommended)
projectService: true

### Performance Considerations

Type-aware linting is significantly slower than basic linting because it requires building TypeScript's type graph. For large projects:

Option 1: Selective type-aware linting

javascript

module.exports = {
  extends: [
    "plugin:@typescript-eslint/recommended",  // Fast rules only
  ],
  overrides: [
    {
      files: ["src/**/*.ts"],
      extends: [
        "plugin:@typescript-eslint/recommended-type-checked",  // Slower, type-aware rules
      ],
      parserOptions: {
        project: "./tsconfig.json",
      },
    },
  ],
};

Option 2: Use allowDefaultProject (not recommended for production)

javascript

parserOptions: {
  project: "./tsconfig.json",
  allowDefaultProject: true,  // Allows linting files outside project
}

This creates a default project for orphaned files but may produce incorrect type information.

### Monorepo Setup

For monorepos with multiple packages:

javascript

// Root .eslintrc.js
module.exports = {
  parser: "@typescript-eslint/parser",
  parserOptions: {
    project: [
      "./tsconfig.json",
      "./packages/*/tsconfig.json",
    ],
    tsconfigRootDir: __dirname,
  },
};

Or use projectService for automatic detection:

javascript

parserOptions: {
  projectService: {
    allowDefaultProject: ["*.js"],
    defaultProject: "./tsconfig.json",
  },
  tsconfigRootDir: __dirname,
}

### Debugging Configuration Issues

Check which files are included in your TypeScript project:

bash

# List all files TypeScript sees
npx tsc --listFiles | grep -v node_modules

# Show detailed resolution
npx tsc --explainFiles

Enable ESLint debug output:

bash

DEBUG=eslint:* npx eslint src/

Check @typescript-eslint parser version compatibility:

bash

npm list @typescript-eslint/parser @typescript-eslint/eslint-plugin typescript

Ensure all three versions are compatible (same major version for parser and plugin).

### Common Gotchas

1. Case sensitivity in include patterns:

json

// Won't match *.JS files on Linux
"include": ["src/**/*.js"]

// Better: be explicit
"include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.js", "src/**/*.jsx"]

2. Exclude takes precedence over include:

json

{
  "include": ["src"],
  "exclude": ["src/scripts"]  // src/scripts won't be included
}

3. Files outside project root:

If files are symlinked or outside your project root, use absolute paths or set tsconfigRootDir properly.

Frequently asked questions

What does "@typescript-eslint cannot parse file without TypeScript" mean?: The "@typescript-eslint cannot parse file without TypeScript" error appears when ESLint attempts to apply type-aware linting rules to a file that isn't part of your TypeScript project. project in your ESLint config, which tells @typescript-eslint/parser to use TypeScript's type checker for enhanced linting rules. json.
How do I fix "@typescript-eslint cannot parse file without TypeScript"?: This error occurs when ESLint is configured to use @typescript-eslint/parser with type-aware linting (parserOptions.project), but tries to lint a file that isn't included in your TypeScript configuration. Files must be in your tsconfig.json's include array or you need to adjust ESLint's configuration to exclude them.
What causes "@typescript-eslint cannot parse file without TypeScript"?: Config files (.eslintrc.js, jest.config.js) aren't in tsconfig.json's include array Files are in directories excluded by tsconfig.json (like build/, dist/, scripts/) parserOptions.project is set but the file isn't part of any referenced tsconfig
Is the "@typescript-eslint cannot parse file without TypeScript" error serious?: It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading

📚TypeScript Official Documentation
📖
@typescript-eslint/parser Documentation(Official Docs)
📖
typescript-eslint - Typed Linting Troubleshooting(Official Docs)
📖
typescript-eslint - FAQs(Official Docs)
Jacob Paris - Solve parserOptions.project bug
🐙
Parser should ignore non-TypeScript files(GitHub)
Bobby Hadz - Parsing Error: Cannot read file tsconfig.json
Bobby Hadz - parserOptions.project has been set
📖
typescript-eslint - parserOptions.project = true(Official Docs)

How to fix @typescript-eslint cannot parse file without TypeScript in TypeScript

Quick fix

What this error means

Typical symptoms

Common causes

How to fix "@typescript-eslint cannot parse file without TypeScript"

Advanced notes

Frequently asked questions

Related errors

Official resources & further reading