vercel/next.js · error · Error

The experimental.allowDevelopmentBuild option requires NODE_

Error message

The experimental.allowDevelopmentBuild option requires NODE_ENV to be explicitly set to 'development'.

What it means

The `experimental.allowDevelopmentBuild` flag permits running a development build outside of the normal dev server, but it only makes sense when `NODE_ENV` is explicitly 'development'. Config normalization throws if the flag is set and `process.env.NODE_ENV` is anything else (production, undefined, test). This prevents accidental dev-bundle code from shipping in production contexts.

Source

Thrown at packages/next/src/server/config.ts:495

      const level =
        typeof expConfig === 'object' && expConfig !== null
          ? (expConfig.level ?? true)
          : expConfig
      // Map 'verbose' to true since browserToTerminal doesn't support 'verbose'
      const normalizedValue = level === 'verbose' ? true : level

      result.logging = {
        ...loggingConfig,
        browserToTerminal: normalizedValue,
      }
    }
  }

  if (
    result.experimental?.allowDevelopmentBuild &&
    process.env.NODE_ENV !== 'development'
  ) {
    throw new Error(
      `The experimental.allowDevelopmentBuild option requires NODE_ENV to be explicitly set to 'development'.`
    )
  }

  // Validate sassOptions.functions is not used with Turbopack
  if (
    process.env.TURBOPACK &&
    result.sassOptions &&
    'functions' in result.sassOptions
  ) {
    throw new Error(
      `The "sassOptions.functions" option is not supported when using Turbopack. ` +
        `Custom Sass functions are only available with webpack. ` +
        `Please remove the "functions" property from your sassOptions in ${configFileName}.`
    )
  }

  // Validate experimental.cssChunking compatibility with the active bundler. Graph mode is

View on GitHub (pinned to 0ae8c72462)

Solutions

Set NODE_ENV=development explicitly before running the dev build command: `NODE_ENV=development next dev`
Remove the allowDevelopmentBuild flag if you don't actually need a development build

Example fix

// before
// next.config.js
module.exports = { experimental: { allowDevelopmentBuild: true } }
// run: next dev  (NODE_ENV unset)
// after
NODE_ENV=development next dev

Defensive patterns

Strategy: validation

Validate before calling

if (config.experimental?.allowDevelopmentBuild && process.env.NODE_ENV !== 'development') {
  throw new Error('Set NODE_ENV=development before enabling allowDevelopmentBuild')
}

Prevention

Set NODE_ENV=development in the script that runs the dev build
Don't enable allowDevelopmentBuild in config shared with production builds

When it happens

Trigger: Setting `experimental: { allowDevelopmentBuild: true }` while NODE_ENV is 'production', 'test', or unset. Common when running a build script that doesn't set NODE_ENV.

Common situations: Enabling allowDevelopmentBuild in a shared config but running `next build` without NODE_ENV=development. CI pipelines that don't export NODE_ENV. Using a process manager that strips env.

Related errors

AI-assisted analysis of vercel/next.js@0ae8c72462 (2026-08-06). Data as JSON: /api/errors/6d90f5a5d5beed67. Report an issue: GitHub.