Next.js "Invalid next.config.js options" - Fix in CI

By Kaveh Alemi·Latchkey

Next validates next.config.js against its schema. A key that was removed, renamed, moved out of experimental, or given the wrong type fails the build.

What this error means

The build prints Invalid next.config.js options detected and lists the unrecognized or misplaced keys.

⚠ Invalid next.config.js options detected:
  Unrecognized key(s) in object: 'swcMinify'
  'experimental.appDir' has been removed.

See more info here: https://nextjs.org/docs/messages/invalid-next-config

Common causes

Key removed or renamed across versions

A Next upgrade removed or moved a config option (e.g. an experimental flag that became stable).

Wrong value type

An option received a string where an object/boolean was expected.

How to fix it

Remove or migrate the invalid key

1. Check the linked docs for the key, then delete it or move it to its new home.

// next.config.js - remove stale keys, move stabilized ones out of experimental
module.exports = { /* valid options only */ };

Match the upgrade guide

1. Follow the Next upgrade guide for the version you moved to and adjust config keys accordingly.

How to prevent it

• Read the Next upgrade guide when bumping majors and reconcile config keys.
• Keep next.config.js minimal so schema drift is easy to spot.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation