Next.js "experimental.appDir" config removed after upgrade in CI

By Daniel Zoghalchali·Latchkey

The App Router left experimental status in Next 13.4. The experimental.appDir flag is no longer a valid option, so an upgraded project that still sets it triggers an invalid-config warning or build failure.

What this error means

After upgrading Next, the build flags experimental.appDir as an unrecognized key under "Invalid next.config.js options detected", or app routes behave unexpectedly because the stale flag is ignored.

⚠ Invalid next.config.js options detected:
⚠     Unrecognized key(s) in object: 'appDir' at "experimental"
⚠ `experimental.appDir` is no longer needed; the App Router is stable.

Common causes

The flag was used to opt into the App Router pre-13.4

Projects on early App Router needed experimental.appDir: true; after 13.4 the option no longer exists.

The config was carried forward across the upgrade

An automated or manual Next bump left the obsolete flag in place, so validation now rejects it.

How to fix it

Remove the experimental.appDir flag

1. Open next.config and delete appDir from the experimental object.
2. Remove the empty experimental block if nothing else remains.
3. Re-run next build.

// next.config.js
- experimental: { appDir: true },
+ // App Router is on by default; no flag needed

Run the upgrade codemod

Next ships codemods that clean up removed flags during a major upgrade.

npx @next/codemod@latest upgrade latest

How to prevent it

• Run the official codemods when upgrading major Next versions.
• Remove experimental flags once a feature stabilizes.
• Read the release notes for removed config keys before bumping.

Frequently asked questions

Related guides

References

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