Next.js warns about invalid options in next.config
A warning that next.config.js has invalid options and names an unexpected propertyShort 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.
Fix it fast
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/null2Match what you see, then jump to its fix
- 1
The key is under experimental, for example experimental.turbopack.The option moved from experimental to the top levelFix - 2
The key is eslint, amp, serverRuntimeConfig, publicRuntimeConfig, experimental.dynamicIO, experimental.useCache, or one of devIndicators.appIsrStatus, buildActivity and buildActivityPosition.The option was removedFix - 3
The 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
- 1
What does the error look like?
A warning that next.config.js has invalid options and names an unexpected propertyA 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 nextConfig3Verify
Start the dev server; the warning for that key should be gone.
npx next devConfirmed by nextjs.org
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 buildConfirmed by nextjs.org
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 info2Fix
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 nextConfig3Verify
Restart next dev.
npx next devConfirmed by nextjs.org
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
Web apps
Upgrading to Next.js 16: middleware becomes proxy, and the other things that break
Missing Required default.js for Parallel Route
Next.js 16 renames middleware.ts to proxy.ts and its exported function to proxy.
6 causes, each with a fixWeb apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
Clerk cannot read its publishable key in a Next.js app
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is undefined
Clerk reads NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY.
3 causes, each with a fixWeb apps
The shell cannot find create-next-app
command not found: create-next-app
create-next-app is not meant to be installed as a shell command.
2 causes, each with a fixWeb apps
ESLint fails with: Cannot find module 'next/babel'
ESLint stops on the first file with a Babel or parser error instead of listing lint results
next/babel is a Babel preset that ships inside the next package.
3 causes, each with a fixWeb apps
Firebase Auth says the API key is not valid
Firebase: Error (auth/api-key-not-valid.-please-pass-a-valid-api-key.)
The apiKey your app sends is either empty, wrong, or blocked.
4 causes, each with a fix