Maaz Zindani

Loading the index…

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

Next.js warns that next.config.js is invalid

Errorwarning Invalid next.config.js

Short answer

The warning means next.config holds an option that is the wrong type, misspelled, or removed in your Next.js version. Type the config with NextConfig so the editor flags it, then move renamed keys: serverComponentsExternalPackages, experimental.turbo, and remove eslint, amp and runtime config options.

  • Applies to 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

    Add the NextConfig type to the file. Your editor then marks the option Next.js does not accept.

    // next.config.ts
    import type { NextConfig } from 'next'
    
    const nextConfig: NextConfig = {
      /* options */
    }
    
    export default nextConfig
  2. 2Match what you see, then jump to its fix

    1. 1The unknown key is under experimental, such as serverComponentsExternalPackages or bundlePagesExternalsAn experimental option was promoted and renamed (Next.js 15)Fix
    2. 2The key is experimental.turbo, eslint, amp, serverRuntimeConfig or publicRuntimeConfigAn option was moved or removed in Next.js 16Fix
    3. 3Options are ignored although the file looks correctThe config file has a name or format Next.js does not loadFix

What does the error look like?

  • warning Invalid next.config.js
  • Invalid next.config.js

Cause 1 of 3

An experimental option was promoted and renamed (Next.js 15)

1Check

Search the config for the old names.

grep -n "serverComponentsExternalPackages\|bundlePagesExternals" next.config.*

2Fix

Use the stable names at the top level of the config.

const nextConfig = {
  serverExternalPackages: ['package-name'],
  bundlePagesRouterDependencies: true,
}
module.exports = nextConfig

3Verify

Start the app again; the warning should be gone.

npx next dev

Confirmed by nextjs.org

Did this fix it?

Cause 2 of 3

An option was moved or removed in Next.js 16

1Check

Compare your keys with the Next.js 16 list. experimental.turbo moved to a top-level turbopack key. The eslint option, the amp config and the runtime config options were removed.

grep -n "turbo\|eslint\|amp\|RuntimeConfig" next.config.*

2Fix

Move turbo to turbopack, delete the removed keys, and use environment variables instead of runtime config. Run ESLint through its own CLI.

const nextConfig = {
  turbopack: {
    // options
  },
}
module.exports = nextConfig

3Verify

Run the build and read the first lines of output.

npx next build

Confirmed by nextjs.org

Did this fix it?

Cause 3 of 3

The config file has a name or format Next.js does not load

1Check

Supported names are next.config.js, next.config.mjs and next.config.ts. A .cjs or .cts extension is not supported. Use export default in .mjs and .ts files, and module.exports in .js.

ls next.config.*

2Fix

Rename the file to a supported name and match the export style to the extension.

mv next.config.cjs next.config.js

3Verify

Restart the dev server.

npx next dev

Confirmed by nextjs.org

Did this fix it?

How do I stop it coming back?

  • Type the config with NextConfig so a bad key fails in the editor, not in the terminal.
  • Read the upgrade guide for each major version before bumping next.
  • Run the official upgrade codemod, which updates renamed options for you.

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.