Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

ESLint no longer reads .eslintrc after upgrading to v9 or v10

ErrorESLint runs after the upgrade but none of the rules from .eslintrc.json apply

Short answer

Yes. Since ESLint 9.0.0 the default config file is eslint.config.js and .eslintrc.* files are no longer searched for. ESLint 10 removed the old format completely. Convert the config with the migration tool, then replace env, extends and plugins with their flat config forms.

  • Applies to ESLint 9, ESLint 10, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check the installed ESLint version and which config files exist. The version tells you which of the causes below you are in.

    npx eslint --version
    ls -a | grep -i -e eslintrc -e eslint.config
  2. 2Match what you see, then jump to its fix

    1. 1The upgrade to v9 happened and only .eslintrc.* files existESLint 9 no longer looks for .eslintrc filesFix
    2. 2The ESLINT_USE_FLAT_CONFIG=false workaround that worked in v9 does nothing after moving to v10ESLint 10 has removed the old formatFix
    3. 3Warnings about unknown keys such as env in the new file, or browser and Node globals reported as undefinedThe old keys were copied over instead of translatedFix
    4. 4Rules apply in one directory but not in another, in a monorepoThe config file is not in a folder ESLint searchesFix

What does the error look like?

  • ESLint runs after the upgrade but none of the rules from .eslintrc.json apply
  • Linting stops because no eslint.config file exists in the project

Cause 1 of 4

ESLint 9 no longer looks for .eslintrc files

1Check

The ESLint 9 migration guide says eslint.config.js is the default format and that eslintrc is deprecated and will not automatically be searched for.

npx eslint --version && ls -a | grep eslintrc

2Fix

Convert the old file with the official migration tool, then review the result by hand. The tool drops the logic of an .eslintrc.js file (functions and conditionals), so rewrite that kind of file manually.

npx @eslint/migrate-config .eslintrc.json

3Verify

Lint the project and confirm the rules you expect are applied.

npx eslint .

Confirmed by eslint.org

Did this fix it?

Cause 2 of 4

ESLint 10 has removed the old format

1Check

The ESLint 10 migration page says the old configuration format is no longer supported. In v9 it could still be enabled by setting ESLINT_USE_FLAT_CONFIG to false, and the page does not give that variable any role in v10.

env | grep ESLINT

2Fix

Remove the environment variable and finish the move to eslint.config.js. There is no escape hatch back to the old format in v10.

# remove it from CI settings and shell profiles
unset ESLINT_USE_FLAT_CONFIG

3Verify

Run ESLint with the variable unset.

npx eslint .

Confirmed by eslint.org

Did this fix it?

Cause 3 of 4

The old keys were copied over instead of translated

1Check

Flat config has no env key. Globals come from the globals package, shared configs are imported and added to the array, and plugins are imported objects.

grep -n -e "env" -e "extends" eslint.config.js

2Fix

Write the file in the flat form and wrap the array in defineConfig.

// eslint.config.js
import js from "@eslint/js";
import globals from "globals";
import { defineConfig } from "eslint/config";

export default defineConfig([
  {
    files: ["**/*.js"],
    plugins: { js },
    extends: ["js/recommended"],
    languageOptions: { globals: { ...globals.browser } },
  },
]);

3Verify

Lint and check that undefined-variable errors for browser globals are gone.

npx eslint .

Confirmed by eslint.org

Did this fix it?

Cause 4 of 4

The config file is not in a folder ESLint searches

1Check

ESLint looks for eslint.config.* in the directory of the file it lints and then in the parent directories until it finds one. A config placed in a sibling folder is never found.

find . -name "eslint.config.*" -not -path "*/node_modules/*"

2Fix

Put the config at the project root (or in the package that needs it), or point to it explicitly with --config.

npx eslint --config eslint.config.js .

3Verify

Lint a file from the folder that failed before.

npx eslint packages/web/src

Confirmed by eslint.org

Did this fix it?

How do I stop it coming back?

  • Read the ESLint migration page before bumping the major version, and bump it in its own commit.
  • Keep one eslint.config.js at the repo root and put overrides in it with files patterns.
  • Run ESLint in CI so a config that loads nothing is noticed on the first push.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

tsconfig rejects allowImportingTsExtensions

An error that allowImportingTsExtensions needs noEmit or emitDeclarationOnly

allowImportingTsExtensions lets files import each other with .ts or .tsx extensions, and TypeScript only allows it together with noEmit or emitDeclarationOnly.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.