Maaz Zindani

Loading the index…

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

Next.js warns about invalid options in next.config

ErrorA warning that next.config.js has invalid options and names an unexpected property

Short answer

Next.js checks your config file and warns about keys it does not know. After an upgrade the usual culprits are options that moved out of experimental, such as turbopack in version 16, and options that were removed, such as eslint, amp or serverRuntimeConfig. Compare each key with the documented options list.

  • 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

    Print the config and read the key the warning names. Then look for that key in the version you run.

    npx next --version
    cat next.config.js next.config.mjs next.config.ts 2>/dev/null
  2. 2Match what you see, then jump to its fix

    1. 1The key is under experimental, for example experimental.turbopack.The option moved from experimental to the top levelFix
    2. 2The key is eslint, amp, serverRuntimeConfig, publicRuntimeConfig, experimental.dynamicIO, experimental.useCache, or one of devIndicators.appIsrStatus, buildActivity and buildActivityPosition.The option was removedFix
    3. 3The key appears in no upgrade guide, for example one belonging to a plugin, or a typo like image or reactStrictmode.The key is misspelled or is not a Next.js option at allFix

What does the error look like?

  • A warning that next.config.js has invalid options and names an unexpected property
  • A setting that used to work is silently ignored after upgrading Next.js

Cause 1 of 3

The option moved from experimental to the top level

1Check

In Next.js 16 experimental.turbopack became a top-level turbopack option. The same release says reactCompiler left experimental, and adapterPath was promoted in 16.2.0.

grep -n "experimental" -A6 next.config.*

2Fix

Move the block to the top level. The upgrade codemod does this for turbopack.

// next.config.ts (Next.js 16)
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  turbopack: {
    // options
  },
  reactCompiler: true,
}

export default nextConfig

3Verify

Start the dev server; the warning for that key should be gone.

npx next dev

Confirmed by nextjs.org

Did this fix it?

Cause 2 of 3

The option was removed

1Check

The Next.js 16 upgrade guide lists these as removed. The eslint option goes with the removal of next lint, and runtime config is replaced by environment variables.

grep -nE "eslint|amp|RuntimeConfig|dynamicIO|useCache|appIsrStatus|buildActivity" next.config.*

2Fix

Delete the key. Use NEXT_PUBLIC_ environment variables in place of publicRuntimeConfig, process.env on the server in place of serverRuntimeConfig, and cacheComponents if you really adopted dynamicIO or useCache.

# .env.local
NEXT_PUBLIC_API_URL="/api"

3Verify

Run a production build and read the first lines of output.

npx next build

Confirmed by nextjs.org

Did this fix it?

Cause 3 of 3

The key is misspelled or is not a Next.js option at all

1Check

Compare the key with the documented options list of next.config.js. Keys are case-sensitive, and plugin options belong inside the plugin's own wrapper call, not at the root.

npx next info

2Fix

Correct the spelling, or move plugin settings into the plugin's call.

// next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  images: { remotePatterns: [{ protocol: 'https', hostname: 'example.com' }] },
}

export default nextConfig

3Verify

Restart next dev.

npx next dev

Confirmed by nextjs.org

Did this fix it?

How do I stop it coming back?

  • Type the config: use next.config.ts with the NextConfig type, or a JSDoc @type comment, so the editor flags unknown keys before Next.js does.
  • Run the upgrade codemod when you change major versions and read its diff.
  • Read the upgrade guide for the target version before bumping next.

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.