Enhancement: Confusing error message when file is linted but not in `parserOptions.project` TSConfig

[jwbth]

Before You File a Proposal Please Confirm You Have Done The Following...

• I have searched for related issues and found none that match my proposal.
• I have searched the current rule list and found no rules that match my proposal.
• I have read the FAQ and my problem is not listed.

Relevant Package

typescript-estree

My proposal is suitable for this project

• I believe my proposal would be useful to the broader TypeScript community (meaning it is not a niche proposal).

Description

The current error message for files that ESLint attempts to lint but aren't included in any TSConfig is confusing and seemingly contradictory:

Parsing error: ESLint was configured to run on `<tsconfigRootDir>/sandbox\test.mjs` using `parserOptions.project`:
- <tsconfigRootDir>/jsconfig.json
- <tsconfigRootDir>/src\jsconfig.json
...
However, none of those TSConfigs include this file.

Problem

The phrase "ESLint was configured to run on [file] using parserOptions.project" is confusing because it sounds like the user explicitly configured ESLint to lint this file with those specific TSConfigs. In reality:

1. ESLint's file inclusion rules determined the file should be linted
2. The parserOptions.project setting exists globally
3. None of the TSConfigs actually cover this file

This creates an apparent contradiction: "configured to run using X" followed by "but X doesn't include this file" makes it sound like the configuration is broken or nonsensical.

Solution

Consider rewording to make the two-step process clearer:

Parsing error: ESLint is attempting to lint `<tsconfigRootDir>/sandbox\test.mjs`, but this file is not included in any of the TSConfigs specified in `parserOptions.project`:
- <tsconfigRootDir>/jsconfig.json
- <tsconfigRootDir>/src\jsconfig.json
...

Either:
- Exclude this file from linting (add it to `ignores`)
- Add this file's location to one of the TSConfig's `include` patterns
- Create a new TSConfig that includes this file and add it to `parserOptions.project`
- Use a separate ESLint configuration for this file without type-aware linting

See the typescript-eslint docs for more info: https://typescript-eslint.io/troubleshooting/typed-linting#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file

This makes it clear that:

1. ESLint wants to lint the file (for reasons separate from parserOptions.project)
2. The type-checking feature requires TSConfig coverage
3. There's a mismatch between these two things

Additional Info

Relevant file: https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/typescript-estree/src/create-program/createProjectProgramError.ts

[bradzacher]

The phrase "ESLint was configured to run on [file] using parserOptions.project" is confusing because it sounds like the user explicitly configured ESLint to lint this file with those specific TSConfigs.

And

In reality ... ESLint's file inclusion rules determined the file should be linted ... The parserOptions.project setting exists globally

What's the difference between these two?

---

This creates an apparent contradiction: "configured to run using X" followed by "but X doesn't include this file" makes it sound like the configuration is broken or nonsensical.

But the config is broken?

• The user configured the linter to run on a file X
• The user configured the linter to run on that file with config parserOptions.project

Either the the list of tsconfigs is broken because the user forgot to add the right one.
Or one of the tsconfigs themselves is broken and doesn't include the right things.
Or the intent was not to lint the file with type-aware linting.
Or the intent was not to lint the file at all.

Either way the user's config is in fact broken - all of these would be fixed by a config change.

---

We also go into deep detail in the linked docs.
https://typescript-eslint.io/troubleshooting/typed-linting#i-get-errors-telling-me-eslint-was-configured-to-run--however-that-tsconfig-does-not--none-of-those-tsconfigs-include-this-file

Which walks through the exact steps to resolve this as well as more detail about the error.

[jwbth]

What's the difference between these two?

Let me try to point out the contradiction more precisely:

I read

ESLint was configured to run on [file] using parserOptions.project

as

According to parserOptions.project, ESLint should run on [file]

(i.e. using means that it was parserOptions.project that was used to configure ESLint to run on [file], and the fact that "ESLint should run on [file]" entails from the content of parserOptions.project).

At the same time,

none of those TSConfigs include this file

This rendered me confused, like, each time I read this error, and then each time I realized it should be read differently.

[kirkwaiblinger]

Yeah, I see what you're saying, it wasn't configured to run on [file] via parserOptions.project, rather, the configuration for [file] has parserOptions.project specified. Personally if there's an easy way to improve the wording, I think it's ok to change it, but I also don't think it's worth spending too much effort on the error message, since as Brad mentioned the linked documentation is more thorough.