nextjs configuration_error ai_generated true

Error: The experimental feature 'X' requires 'experimental.X' to be enabled in next.config.js

ID: nextjs/experimental-feature-config

Also available as: JSON · Markdown
91%Fix Rate
90%Confidence
80Evidence
2023-01-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
14 active — — —

Root Cause

Next.js gates certain features behind experimental flags in next.config.js. When code uses an experimental API (e.g., serverActions, ppr, instrumentationHook, typedRoutes, serverComponentsExternalPackages) without the corresponding config flag, this error is thrown at build or dev startup. In Next.js 14, some previously experimental features have been promoted to stable (e.g., Server Actions became stable in 14.0), while others remain behind experimental flags. The confusion often arises from outdated documentation, blog posts referencing features that changed status between versions, or copying configuration from a different Next.js version. Fix by adding the correct experimental flag or by checking if the feature has been promoted to stable in your version.

generic

Workarounds

  1. 93% success Add the specific experimental flag to next.config.js 
    Add the required experimental flag to your next.config.js: // next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    // Add the specific flag mentioned in the error:
    ppr: true,                    // Partial Prerendering
    typedRoutes: true,            // Type-safe routes
    instrumentationHook: true,    // Instrumentation
    serverComponentsExternalPackages: ['sharp', 'prisma'],
  },
};
module.exports = nextConfig;

Only add the flag that the error message specifies. Restart the dev server after changing next.config.js
  2. 90% success Check if the feature has been promoted to stable in Next.js 14 and remove the experimental prefix 
    Several features were promoted to stable in Next.js 14: Server Actions (no longer need experimental.serverActions), App Router (stable since 13.4). Check the Next.js 14 release notes and upgrade guide. If you find the feature is now stable: 1) Remove the experimental flag, 2) Follow the migration guide for any API changes. Example: if you had experimental: { serverActions: true }, remove it in Next.js 14 since Server Actions are stable. For features that moved from experimental to top-level config: transpilePackages (was experimental.transpilePackages), serverComponentsExternalPackages (moved to top-level in 14.x). Update accordingly: const nextConfig = { serverComponentsExternalPackages: ['sharp'] };
  3. 87% success Use a conditional config to enable experimental features only in specific environments 
    For features still under development, enable them conditionally: // next.config.js
const nextConfig = {
  experimental: {
    ...(process.env.ENABLE_PPR === 'true' && { ppr: true }),
    ...(process.env.NODE_ENV === 'development' && { typedRoutes: true }),
  },
};
module.exports = nextConfig;

This allows you to test experimental features in development while keeping production builds on stable features. Set ENABLE_PPR=true in .env.local for local development. This approach reduces risk when experimenting with features that may affect build output or runtime behavior

Dead Ends

Common approaches that don't work:

  1. Enabling every experimental flag at once to avoid configuration errors 75% fail

    Experimental flags can conflict with each other and may introduce breaking behavior changes. Some experimental features are mutually exclusive or modify the same build pipeline in incompatible ways. Enabling untested combinations can cause build failures, runtime errors, or silently incorrect behavior. Additionally, experimental features may be removed or renamed in future versions, creating upgrade burden

  2. Downgrading Next.js to a version where the feature was not experimental 85% fail

    If the feature was experimental in the earlier version, it either did not exist or was in a less stable state. Downgrading typically moves you further from stability, not closer. Features graduate from experimental to stable in newer versions, so upgrading is usually the correct direction. Downgrading also forfeits security patches and bug fixes

  3. Setting the experimental flag in environment variables instead of next.config.js 95% fail

    Next.js experimental flags must be set in next.config.js (or next.config.mjs/ts). They cannot be configured via environment variables, .env files, or command-line arguments. The Next.js config loader reads these flags from the config file directly during build initialization, before environment variable processing for runtime config

Error Chain

Leads to:
Preceded by: