Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

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.

~5 min readTypeScript
#ESLint#TypeScript#Flat Config#Linting
A single root config slab replacing a stack of nested folder tabs, amber highlight on the dropped tab

Introduction & Quick Summary

Symptom. Lint stops working in one of two ways, and the quieter one is worse:

code
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-guide

Exit 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:

bash
npx @eslint/migrate-config .eslintrc.json npm install -D @eslint/js typescript-eslint globals npx eslint .
js
// 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:

bash
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:

js
// 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 .eslintrcFlat eslint.config.jsConsequence of missing the change
cascading files per directoryone root file, an arraynested configs are ignored
extends: ["plugin:x/recommended"]import the object and spread itconfig silently absent
plugins: ["react"]plugins: { react: reactPlugin }plugin "react" was conflicted errors
parser / parserOptionslanguageOptions.parser / .parserOptionsTS syntax fails to parse
env: { browser: true }languageOptions.globals from globalsno-undef on window, process
overrides: [{ files, rules }]a config object with filesoverride never applies
.eslintignore / ignorePatternsignores entrygenerated folders get linted
--ext .ts on the CLIfiles patterns onlyno files matched, or all files linted
VersionMessageLegacy .eslintrcEscape hatch
ESLint 8reads .eslintrc.*supportednone needed
ESLint 9`couldn't find an eslint.config.(jsmjscjs) file`
ESLint 10couldn't find an eslint.config.* fileremovednone

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:

js
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:

js
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:

json
// .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:

js
// packages/eslint-config/base.mjs import js from "@eslint/js"; import globals from "globals"; export default [js.configs.recommended, { languageOptions: { globals: globals.node } }];
js
// 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:

js
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.json in the repository after migrating. Some editors still read it and disagree with the CLI.
  • Relying on ESLINT_USE_FLAT_CONFIG=false as the fix. ESLint 10 ignores it.
  • Forgetting globals. Flat config has no env, so process and window become no-undef errors.
  • Putting ignores next to other keys and expecting a global ignore.
  • Assuming --ext still 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 on parserServices.

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 documentation

The TypeScript documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit TypeScript work — they run entirely in this browser tab, so nothing you paste leaves your device.

All TypeScript guides

More in TypeScript

All TypeScript guides

The guides filed next to this one in TypeScript, in library order.