Fixing ESLint "Cannot read file 'tsconfig.json'" Error

The "Parsing error: Cannot read file '.../tsconfig.json'" error occurs when ESLint cannot locate your TypeScript configuration file. This is a common issue that appears as red underlines in your editor, even when your code compiles successfully.

Root Cause

By default, the TypeScript ESLint parser resolves tsconfig.json files relative to the current working directory. If ESLint runs from a different directory than where your tsconfig.json is located, you'll encounter this error.

Solutions

1. Set tsconfigRootDir (Recommended)

The most straightforward fix is to specify the root directory containing your tsconfig.json file:

// .eslintrc.js
module.exports = {
  // ... other config
  parserOptions: {
    project: "tsconfig.json",
    tsconfigRootDir: __dirname, // Add this line
    sourceType: "module",
  },
};

For ESLint v9 flat config format:

// eslint.config.mjs
import tseslint from 'typescript-eslint'

export default tseslint.config(
  // ... other config
  {
    languageOptions: {
      parserOptions: {
        project: 'tsconfig.json',
        tsconfigRootDir: import.meta.dirname,
      },
    },
  },
);

2. Use project: true for Dynamic Resolution (TypeScript ESLint v5.52.0+)

Recent versions support automatic resolution of the nearest tsconfig.json:

module.exports = {
  parserOptions: {
    project: true, // Automatically find nearest tsconfig.json
    tsconfigRootDir: __dirname,
    sourceType: "module",
  },
};

This approach automatically searches up the directory tree from each source file to find the appropriate tsconfig.json.

3. Specify Full Path to tsconfig.json

If you have a non-standard project structure, explicitly define the path:

module.exports = {
  parserOptions: {
    project: "./path/to/your/tsconfig.json",
    tsconfigRootDir: __dirname,
    sourceType: "module",
  },
};

4. Multi-project/Monorepo Configuration

For monorepos with multiple TypeScript projects, specify all relevant configs:

{
  "parserOptions": {
    "project": [
      "packages/frontend/tsconfig.json",
      "packages/backend/tsconfig.json",
      "tsconfig.base.json"
    ],
    "tsconfigRootDir": __dirname
  }
}

5. Angular-specific Configuration

Angular projects often require a different approach:

{
  "overrides": [
    {
      "files": ["*.ts"],
      "parserOptions": {
        "project": ["**/tsconfig.json"]
      }
    }
  ]
}

Editor-specific Solutions

Visual Studio Code

Add to your .vscode/settings.json:

{
  "eslint.workingDirectories": [
    {
      "mode": "auto"
    }
  ]
}

Or specify the working directory explicitly:

{
  "eslint.workingDirectories": ["src"]
}

IntelliJ/WebStorm

If using IntelliJ-based IDEs:

1. Go to ESLint settings
2. Select "Manual ESLint configuration"
3. Set the working directory to your project root
4. Specify the path to your ESLint package

Troubleshooting Common Issues

File Not Included in Project Error

If you encounter errors about specific files not being included in your project:

error  Parsing error: "parserOptions.project" has been set for @typescript-eslint/parser.
The file does not match your project config: .eslintrc.js.
The file must be included in at least one of the projects provided

TIP

Add an include array to your tsconfig.json that encompasses all files you want to lint:

{
  "include": [
    "src/**/*",
    "tests/**/*",
    ".eslintrc.js" // Include config files if needed
  ]
}

WSL/Remote Development

If working with WSL or remote containers, ensure you have the appropriate VS Code extensions installed:

• Remote - WSL for Windows Subsystem for Linux
• Remote Development for containers and SSH

Best Practices

1. Always set tsconfigRootDir to prevent directory resolution issues
2. Keep ESLint config close to code - preferably in the same directory as your tsconfig.json
3. Use consistent working directories across your team and CI environment
4. Update TypeScript ESLint regularly to benefit from improvements and bug fixes

When to Use projectService (TypeScript ESLint v8+)

For large projects, consider using the newer projectService option:

module.exports = {
  parserOptions: {
    projectService: true,
    tsconfigRootDir: __dirname,
  },
};

This option provides better performance for typed linting in large codebases by leveraging TypeScript's project service.

INFO

The projectService option is recommended for TypeScript ESLint v8+ as it offers improved configuration and performance for typed linting.

By implementing these solutions, you should resolve the "Cannot read file 'tsconfig.json'" error and ensure ESLint properly analyzes your TypeScript code.