Solved: Next.js ESLint Unknown Options 'useEslintrc' and 'extensions' Error

You've just upgraded to ESLint 9, excited to use the latest tooling in your Next.js project. You run next lint like you always do, and then—everything breaks. Your terminal fills with errors about "Unknown options" for things like useEslintrc, extensions, and resolvePluginsRelativeTo.

If you're staring at this Next.js ESLint 9 extensions error wondering what went wrong, you're not alone. This is one of the most common issues developers face after upgrading to ESLint 9, and the good news is it's completely fixable.

In this guide, I'll explain exactly why this happens, walk you through the solutions, and help you avoid this problem in future upgrades.

The Problem — Running 'next lint' with ESLint 9 Fails

When you run npm run lint or next lint in a Next.js project that uses ESLint 9, you get an error that looks something like this:

❌ What you see:
 
➜ npm run lint
 
> lint
> next lint
 
Invalid Options:
- Unknown options: useEslintrc, extensions, resolvePluginsRelativeTo, rulePaths, ignorePath, reportUnusedDisableDirectives
- 'extensions' has been removed.
- 'resolvePluginsRelativeTo' has been removed.
- 'ignorePath' has been removed.
- 'rulePaths' has been removed. Please define your rules using plugins.
- 'reportUnusedDisableDirectives' has been removed. Please use the 'overrideConfig.linterOptions.reportUnusedDisableDirectives' option instead.

This error is especially frustrating because your ESLint configuration looks perfectly normal. You probably have a standard .eslintrc.json file like this:

{
  "extends": "next/core-web-vitals"
}

Nothing fancy. Just the basic Next.js recommended setup. So why is it failing?

The issue isn't with your configuration file—it's with how Next.js internally calls ESLint, and ESLint 9 no longer supports those internal calls.

Why ESLint 9 Breaks Next.js Linting

To understand this Next.js ESLint 9 extensions error, you need to know what changed in ESLint 9. ESLint made a massive architectural shift called the "flat config" system.

The Old Way (ESLint 8 and Earlier)

In ESLint 8, you could:

• Use .eslintrc.json, .eslintrc.js, or .eslintrc.yaml files
• Pass options like --ext .js,.jsx,.ts,.tsx on the command line
• Use the useEslintrc option in the Node.js API to control whether config files were loaded

These options were deeply embedded in ESLint's architecture, and tools like Next.js relied on them internally.

The New Way (ESLint 9)

ESLint 9 introduces "flat config" as the default. This means:

• Configuration lives in eslint.config.js (a single JavaScript file)
• Many CLI options and API parameters were completely removed
• The old .eslintrc.* files are deprecated

Here's the list of options that ESLint 9 removed, which Next.js was using internally:

The Root Cause

When you run next lint, Next.js doesn't just call ESLint directly. It uses a custom wrapper located in packages/next/src/cli/next-lint.ts. This wrapper passes configuration options to ESLint's Node.js API.

The problem? Next.js was passing options like useEslintrc: true and extensions: ['.js', '.jsx', '.ts', '.tsx'] to ESLint. These options worked fine in ESLint 8, but ESLint 9 throws an error because they no longer exist.

This is a documented issue in the Next.js repository (GitHub Issue #64409), and the Vercel team is aware of it.

The Solution — Getting Your Project Working Again

There are several ways to fix this Next.js ESLint 9 extensions error. Choose the one that best fits your situation.

Solution 1: Downgrade to ESLint 8 (Recommended for Beginners)

The simplest and most reliable fix is to downgrade to ESLint 8. This requires minimal changes and gets your project working immediately.

✅ The fix:
 
# Uninstall ESLint 9
npm uninstall eslint
 
# Install ESLint 8
npm install eslint@8 --save-dev

After downgrading, verify your package.json shows ESLint 8:

{
  "devDependencies": {
    "eslint": "^8.57.0",
    "eslint-config-next": "14.2.0"
  }
}

Run next lint again, and it should work:

✅ Expected output:
 
➜ npm run lint
 
> lint
> next lint
 
✔ No ESLint warnings or errors

Why this works: ESLint 8 still supports all the options that Next.js internally uses. By downgrading, you restore compatibility until Next.js updates their linting logic.

Solution 2: Use the ESLint CLI Directly (Skip next lint)

If you want to stay on ESLint 9, you can bypass next lint entirely and run ESLint directly. This requires setting up the flat config system.

Step 1: Create an eslint.config.mjs file in your project root:

// eslint.config.mjs
import { FlatCompat } from "@eslint/eslintrc";
import path from "path";
import { fileURLToPath } from "url";
 
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
 
const compat = new FlatCompat({
  baseDirectory: __dirname,
});
 
export default [
  ...compat.extends("next/core-web-vitals"),
  {
    ignores: [".next/*", "node_modules/*"],
  },
];

Step 2: Install the compatibility package:

npm install @eslint/eslintrc --save-dev

Step 3: Update your package.json script to use the ESLint CLI directly:

{
  "scripts": {
    "lint": "eslint . --max-warnings 0"
  }
}

Step 4: Remove or rename your old .eslintrc.json file (ESLint 9's flat config won't use it):

mv .eslintrc.json .eslintrc.json.backup

Now npm run lint will use ESLint directly, bypassing Next.js's wrapper entirely.

Trade-offs: This approach works, but you lose some Next.js-specific linting features that next lint provides, such as automatic caching and integration with the build process.

Solution 3: Use the ESLINT_USE_FLAT_CONFIG Environment Variable

ESLint 9 provides an escape hatch to temporarily use the legacy configuration system:

ESLINT_USE_FLAT_CONFIG=false npm run lint

Or add it to your npm script:

{
  "scripts": {
    "lint": "ESLINT_USE_FLAT_CONFIG=false next lint"
  }
}

Important: This is a temporary workaround. ESLint has deprecated the legacy config system, and future versions may remove this option entirely. Use this only as a short-term fix while you plan your migration.

Solution 4: Wait for Next.js to Add ESLint 9 Support

The Next.js team is actively working on ESLint 9 support. If you're not in a rush, you can:

1. Track GitHub Issue #64409 for updates
2. Pin your ESLint version to 8 in the meantime
3. Upgrade to ESLint 9 once Next.js releases official support

Prevention & Best Practices

Now that you've fixed the immediate problem, let's talk about how to avoid similar issues in the future.

1. Check Compatibility Before Upgrading

Before upgrading any major dependency in your Next.js project, check compatibility with eslint-config-next:

# Check the current version of eslint-config-next
npm list eslint-config-next
 
# Check which ESLint versions it supports
npm info eslint-config-next peerDependencies

As of early 2024, eslint-config-next still lists ESLint 8 as a peer dependency. Upgrading ESLint beyond what's officially supported is asking for trouble.

2. Pin Your Dependencies

Instead of using caret (^) or tilde (~) version ranges, consider pinning major dependencies:

{
  "devDependencies": {
    "eslint": "8.57.0",
    "eslint-config-next": "14.2.0"
  }
}

This prevents accidental upgrades when running npm install on a fresh clone.

3. Read the Changelog Before Major Updates

ESLint's migration guide (eslint.org/docs/latest/use/migrate-to-9.0.0) clearly documents all breaking changes. Spending 10 minutes reading changelogs can save hours of debugging.

4. Test in Isolation

Before upgrading ESLint in your main project, test the upgrade in a branch or a minimal reproduction:

# Create a test branch
git checkout -b test/eslint-9-upgrade
 
# Attempt the upgrade
npm install eslint@9 --save-dev
 
# Run linting
npm run lint
 
# If it fails, you haven't affected your main branch
git checkout main

5. Watch for Next.js Release Notes

Major Next.js releases often include ESLint-related updates. Check the release notes at nextjs.org/blog before upgrading to understand what's changed.

Understanding the Flat Config System

If you're curious about ESLint's flat config system, here's a quick primer. Understanding this will help you when Next.js eventually requires ESLint 9.

The flat config is a single eslint.config.js (or .mjs, .cjs) file that exports an array of configuration objects:

// eslint.config.js
export default [
  {
    files: ["**/*.js", "**/*.jsx", "**/*.ts", "**/*.tsx"],
    rules: {
      "no-unused-vars": "error",
    },
  },
  {
    files: ["**/*.test.js"],
    rules: {
      "no-unused-vars": "off", // More lenient for tests
    },
  },
];

Key differences from the old system:

• No more cascading config files (.eslintrc in every directory)
• Plugins are imported directly, not referenced by string
• extends is replaced by spreading arrays
• The configuration is more explicit and predictable

Key Takeaways

• The error is caused by ESLint 9, not your configuration. ESLint 9's flat config system removed options that Next.js internally uses.
• Downgrading to ESLint 8 is the simplest fix for most projects and has no downsides for now.
• You can bypass next lint and use ESLint directly with flat config if you need ESLint 9 features.
• This is a known issue tracked in GitHub Issue #64409. The Next.js team is working on it.
• Always check compatibility before upgrading major dependencies, especially linting tools that integrate deeply with your framework.

Next Steps

1. Fix the immediate issue by downgrading to ESLint 8 using npm install eslint@8 --save-dev
2. Pin your ESLint version in package.json to prevent accidental upgrades
3. Bookmark GitHub Issue #64409 to get notified when Next.js adds ESLint 9 support
4. Learn about flat config so you're ready when Next.js migrates—the ESLint migration guide is an excellent resource
5. Test your linting after any major upgrade by running npm run lint before committing changes

The Next.js ESLint 9 extensions error is frustrating, but it's a temporary pain point in the JavaScript ecosystem's evolution. ESLint's flat config is genuinely better architecture, and once the ecosystem catches up, these issues will be behind us.

For now, stick with ESLint 8, and you'll be fine.