ESLint 9: the flat config error and why .eslintrc stopped loading
Flat config is one array, one root file, and no string extends. Here is the conversion, the four settings with no equivalent, and the editor trap.

Introduction & Quick Summary
Symptom. Lint stops working in one of two ways, and the quieter one is worse:
Oops! Something went wrong! :(
ESLint: 9.39.0
ESLint couldn't find an eslint.config.(js|mjs|cjs) file.
From ESLint v9.0.0, the default configuration file is now eslint.config.js.
If you are using a .eslintrc.* file, please follow the migration guide:
https://eslint.org/docs/latest/use/configure/migration-guideExit code 2, so CI fails on the lint step. In the editor, the extension shows no diagnostics at all, and a team can merge code for a week before anyone notices that nothing is being checked yet.
Cause. ESLint 9 made the flat config format the default and stopped reading .eslintrc.* and .eslintignore. It looks for eslint.config.js, eslint.config.mjs, eslint.config.cjs, and the TypeScript equivalents. A project that only has .eslintrc.json has no configuration as far as ESLint 9 is concerned. ESLint 10 goes further and removes the legacy format entirely, so ESLINT_USE_FLAT_CONFIG=false is a bridge, not a fix.
Fix. Convert once, then delete the old files so nobody edits them by accident:
npx @eslint/migrate-config .eslintrc.json
npm install -D @eslint/js typescript-eslint globals
npx eslint .// eslint.config.mjs — a hand-written equivalent for a TypeScript project
import js from "@eslint/js";
import tseslint from "typescript-eslint";
import globals from "globals";
export default tseslint.config(
{ ignores: ["dist/", "coverage/", ".next/"] },
js.configs.recommended,
...tseslint.configs.recommended,
{
files: ["**/*.{ts,tsx}"],
languageOptions: {
globals: { ...globals.browser, ...globals.node },
parserOptions: { projectService: true, tsconfigRootDir: import.meta.dirname },
},
},
);The rest of this guide covers what the converter produces when plugins lack flat configs, the four settings that have no flat equivalent, and the traps that survive a "successful" migration.
Core Mechanics, Signatures & Reproducible Setup
Flat config is one array of plain objects. There is no cascade, no extends by string name, and no plugin resolution: what you import is what runs. Every object may set files, ignores, languageOptions, plugins, rules, settings and linterOptions, and later objects override earlier ones for matching files.
Reproduce the error in a scratch directory to see the exact wording your version prints:
mkdir /tmp/eslint9 && cd /tmp/eslint9
npm init -y >/dev/null
echo '{ "rules": { "no-unused-vars": "error" } }' > .eslintrc.json
echo 'const unused = 1;' > index.js
npm install -D eslint@9
npx eslint index.js ; echo "exit=$?"ESLint 9 prints couldn't find an eslint.config.(js|mjs|cjs) file and exits 2; ESLint 10 prints couldn't find an eslint.config.* file and also exits 2. Add an eslint.config.mjs and the same command exits 1 with the real lint error.
The converter is the fastest way to a working baseline, and worth reading rather than committing blindly. It wraps eslintrc-only plugins in FlatCompat:
// what the converter emits when a plugin has no flat config yet
import { FlatCompat } from "@eslint/eslintrc";
import js from "@eslint/js";
import path from "node:path";
import { fileURLToPath } from "node:url";
const compat = new FlatCompat({
baseDirectory: path.dirname(fileURLToPath(import.meta.url)),
recommendedConfig: js.configs.recommended,
});
export default [
...compat.extends("plugin:some-old-plugin/recommended"),
{ files: ["**/*.ts"], rules: { "no-console": "warn" } },
];FlatCompat is a bridge for eslintrc-only plugins. It works, and it also hides which plugin version you are really running, so treat each compat.extends as a to-do.
Key Comparison Table
Legacy .eslintrc | Flat eslint.config.js | Consequence of missing the change |
|---|---|---|
| cascading files per directory | one root file, an array | nested configs are ignored |
extends: ["plugin:x/recommended"] | import the object and spread it | config silently absent |
plugins: ["react"] | plugins: { react: reactPlugin } | plugin "react" was conflicted errors |
parser / parserOptions | languageOptions.parser / .parserOptions | TS syntax fails to parse |
env: { browser: true } | languageOptions.globals from globals | no-undef on window, process |
overrides: [{ files, rules }] | a config object with files | override never applies |
.eslintignore / ignorePatterns | ignores entry | generated folders get linted |
--ext .ts on the CLI | files patterns only | no files matched, or all files linted |
| Version | Message | Legacy .eslintrc | Escape hatch |
|---|---|---|---|
| ESLint 8 | reads .eslintrc.* | supported | none needed |
| ESLint 9 | `couldn't find an eslint.config.(js | mjs | cjs) file` |
| ESLint 10 | couldn't find an eslint.config.* file | removed | none |
Practical Edge Cases, Error Fixes & Deep Dive Code Examples
1. ignores in the wrong place does nothing
A config object that contains both ignores and other keys applies the ignores only to that object. A config object with ignores alone is a global ignore, and this is the only form that replaces .eslintignore:
export default [
{ ignores: ["dist/", "coverage/", "*.config.js"] }, // global
js.configs.recommended,
{ ignores: ["legacy/"], rules: { "no-console": "off" } }, // NOT global
];The second object above is a common mistake copied from a blog post: it looks like a global ignore and behaves like a per-object filter, so legacy/ is still linted by earlier configs.
2. TypeScript needs a parser and a project, not just a plugin
typescript-eslint v8 is the flat-config package, and its config() helper exists mainly to type-check the config itself. Without projectService (or an explicit project), the type-aware rules either do nothing or throw You have used a rule which requires parserServices to be generated:
import tseslint from "typescript-eslint";
export default tseslint.config(
js.configs.recommended,
tseslint.configs.recommendedTypeChecked,
{
files: ["**/*.{ts,tsx}"],
languageOptions: {
parserOptions: { projectService: true, tsconfigRootDir: import.meta.dirname },
},
},
{
files: ["**/*.config.{js,ts,mjs}"],
extends: [tseslint.configs.disableTypeChecked],
},
);The last block matters: config files are usually outside include in tsconfig.json, and type-aware linting of them fails with file was not found in any of the provided project(s).
3. The editor disagrees with the CLI
Editor extensions run their own copy of ESLint and resolve the config upwards from the file's directory. A stale eslint.experimental.useFlatConfig setting or an old extension can keep the editor silent:
// .vscode/settings.json
{ "eslint.useFlatConfig": true, "eslint.validate": ["javascript", "typescript", "typescriptreact"] }Restart the extension host after editing it. If the CLI is clean and the editor still shows nothing, open the ESLint output channel: it logs the config path it loaded, which is the fastest way to find a second config closer to the file.
4. Choosing what gets linted
--ext is gone. File selection is now a files pattern, and a pattern that matches nothing turns lint into a no-op success:
{
"scripts": {
"lint": "eslint .",
"lint:fix": "eslint . --fix",
"lint:ci": "eslint . --max-warnings=0"
}
}eslint . lints every file the config matches, so a config with files: ["**/*.ts"] and no JavaScript entry silently stops checking .js files. Add the extensions you actually ship.
5. Shared configs and monorepos
In a monorepo the old pattern of one .eslintrc per package becomes one root config with files patterns, plus a shared config package that exports an array:
// packages/eslint-config/base.mjs
import js from "@eslint/js";
import globals from "globals";
export default [js.configs.recommended, { languageOptions: { globals: globals.node } }];// eslint.config.mjs at the root
import base from "./packages/eslint-config/base.mjs";
export default [
...base,
{ files: ["apps/web/**/*.{ts,tsx}"], languageOptions: { globals: globals.browser } },
];Resolution is plain Node resolution, so a missing config fails loudly instead of being skipped by name.
6. Prettier, and what comes last
Flat config is order-sensitive. eslint-config-prettier must be last so it can turn off formatting rules that other configs enabled:
import prettier from "eslint-config-prettier";
export default tseslint.config(
js.configs.recommended,
...tseslint.configs.recommended,
prettier,
);Without it, a migrated project often reports hundreds of indentation and quote errors that the v8 setup never produced, because plugin:prettier/recommended used to arrive through extends.
Common Compilation/Runtime Mistakes & Version Gotchas
- Leaving
.eslintrc.jsonin the repository after migrating. Some editors still read it and disagree with the CLI. - Relying on
ESLINT_USE_FLAT_CONFIG=falseas the fix. ESLint 10 ignores it. - Forgetting
globals. Flat config has noenv, soprocessandwindowbecomeno-undeferrors. - Putting
ignoresnext to other keys and expecting a global ignore. - Assuming
--extstill narrows the run. It does not exist in flat config. - Migrating eslintrc-only plugins without
FlatCompat. The run throws on an unknown plugin key. - Committing the converted config without installing the packages it imports. It fails at import time.
- Type-aware rules without
projectService. They skip files or crash onparserServices.
Compare the converted config with the original line by line using the text diff tool, confirm the resolved package list in the manifest with the JSON formatter, and inspect the exact plugin-matching patterns with the regex tester before adding a broad files glob.
Reference: the configuration file documentation, the migration guide, and the ESLint 9 migration notes.
Official references
primary documentationThe TypeScript documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit TypeScript work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related TypeScript guides
All TypeScript guidesTS1294: This syntax is not allowed when erasableSyntaxOnly is enabled
Enums, namespaces and parameter properties emit code, so erasable mode rejects them. Convert each to an erasable form without changing call sites.
TS2742: the inferred type cannot be named without a reference
Type checking passes and only declaration emit fails. Annotate the exported boundary so consumers can resolve the emitted type.
TypeScript 7 native tsc: moduleResolution, baseUrl and API errors
The native compiler changes three defaults and drops the compiler API. Fix tsconfig first, then alias TypeScript 6 for eslint and ts-node.
TypeScript TS2769: No overload matches this call
Every overload rejected an argument. Read the failing signature, fix the one incompatible property, and know when a cast is honest.
More in TypeScript
All TypeScript guidesThe guides filed next to this one in TypeScript, in library order.