Maaz Zindani

Loading the index…

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

ESLint 9 ignores or breaks the Next.js lint config

ErrorESLint 9 is not working properly with Next 15

Short answer

ESLint 9 uses the flat config format by default and looks for eslint.config.js or .mjs, not an old .eslintrc file. For Next.js either write eslint.config.mjs, using eslint-config-next directly on Next.js 16 or FlatCompat on 15, and run the ESLint CLI. Next.js 16 also removes the next lint command.

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

Fix it fast

  1. 1Find out which cause you have

    See which config files exist and which ESLint and Next.js versions are installed.

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

    1. 1Only .eslintrc.json or .eslintrc.js exists, and ESLint does not apply the Next.js rules.The project still uses an .eslintrc fileFix
    2. 2You use extends: ['next/core-web-vitals'] and ESLint 9 rejects or ignores it.Next.js 15 with a shareable config in the old formatFix
    3. 3next lint no longer works after upgrading, or the eslint key in next.config is flagged.You still run next lint on Next.js 16Fix
    4. 4A long .eslintrc.json with many plugins and overrides.An old eslintrc file is kept and you want to convert itFix

What does the error look like?

  • ESLint 9 is not working properly with Next 15

Cause 1 of 4

The project still uses an .eslintrc file

1Check

Flat config has been the default format since ESLint v9.0.0, so ESLint looks for eslint.config.js and its variants.

ls -a | grep -iE "eslintrc|eslint.config"

2Fix

Create eslint.config.mjs. On Next.js 16 use the flat config that eslint-config-next exports.

// eslint.config.mjs  (eslint-config-next 16)
import { defineConfig, globalIgnores } from 'eslint/config'
import nextVitals from 'eslint-config-next/core-web-vitals'

export default defineConfig([
  ...nextVitals,
  globalIgnores(['.next/**', 'out/**', 'build/**', 'next-env.d.ts']),
])

3Verify

Run ESLint on the project and see Next.js rules applied.

npx eslint .

Confirmed by nextjs.org

Did this fix it?

Cause 2 of 4

Next.js 15 with a shareable config in the old format

1Check

Shareable configs written for the old format must be translated. The ESLint migration guide uses FlatCompat from @eslint/eslintrc for that, and the Next.js 15 docs use it for the next configs.

npm ls @eslint/eslintrc

2Fix

Install @eslint/eslintrc and wrap the Next.js config with FlatCompat in eslint.config.mjs.

// eslint.config.mjs  (Next.js 15)
import { FlatCompat } from '@eslint/eslintrc'

const compat = new FlatCompat({ baseDirectory: import.meta.dirname })

export default [
  ...compat.config({
    extends: ['next/core-web-vitals', 'next/typescript'],
  }),
]

3Verify

Lint a file that breaks a rule on purpose, for example an img element, and see the warning.

npx eslint app

Confirmed by nextjs.org

Did this fix it?

Cause 3 of 4

You still run next lint on Next.js 16

1Check

Starting with Next.js 16, next lint is removed, and the eslint option in the Next config is no longer needed.

grep -n "next lint\|eslint" package.json next.config.*

2Fix

Call ESLint directly from your scripts and delete the eslint option from the Next config.

// package.json
"scripts": {
  "lint": "eslint ."
}

3Verify

Run the script.

npm run lint

Confirmed by nextjs.org

Did this fix it?

Cause 4 of 4

An old eslintrc file is kept and you want to convert it

1Check

ESLint ships a migrator that turns an eslintrc file into a flat config as a starting point. Its output may need manual edits.

ls .eslintrc*

2Fix

Run the migrator, then review the generated file and remove what Next.js already provides.

npx @eslint/migrate-config .eslintrc.json

3Verify

Run ESLint and compare its results with the old setup.

npx eslint .

Confirmed by eslint.org

Did this fix it?

How do I stop it coming back?

  • Upgrade ESLint and eslint-config-next together, not one at a time.
  • Keep one config file only, so it is clear which one ESLint reads.
  • Run the lint script in CI, because a config that ESLint cannot read can fail quietly in an editor.

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

Next step

Want this handled for good?

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