`experimental.turbopackChunkingHeuristics` has been renamed

Error message

`experimental.turbopackChunkingHeuristics` has been renamed to `experimental.turbopackChunking`. Please update your ${configFileName} file accordingly.

What it means

Thrown at config.ts:2082 when `experimental.turbopackChunkingHeuristics` is present in the user config. The option was renamed (and restructured) to `experimental.turbopackChunking`. The old key is rejected outright during config normalization.

Source

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

    // `experimental.turbopackGenerateComponentChunks` has moved into
    // `experimental.turbopackChunking.generateComponentChunks`.
    if (
      (userConfig.experimental as any)?.turbopackGenerateComponentChunks !==
      undefined
    ) {
      throw new Error(
        `\`experimental.turbopackGenerateComponentChunks\` has been moved to \`experimental.turbopackChunking.generateComponentChunks\`. Please update your ${configFileName} file accordingly.`
      )
    }

    // `experimental.turbopackChunkingHeuristics` has been renamed to
    // `experimental.turbopackChunking`.
    if (
      (userConfig.experimental as any)?.turbopackChunkingHeuristics !==
      undefined
    ) {
      throw new Error(
        `\`experimental.turbopackChunkingHeuristics\` has been renamed to \`experimental.turbopackChunking\`. Please update your ${configFileName} file accordingly.`
      )
    }

    // Always validate the config against schema in non minimal mode
    if (!process.env.NEXT_MINIMAL && !silent) {
      await validateConfigSchema(
        userConfig,
        configFileName,
        curLog.warn,
        (messages) => {
          // Capture validation messages for MCP error reporting
          if (messages.length > 0) {
            const fullMessage = messages.join('\n')
            NextInstanceErrorState.nextConfig.push(new Error(fullMessage))
          }
        }
      )

View on GitHub (pinned to 0ae8c72462)

Solutions

Rename to `experimental.turbopackChunking` and nest the relevant sub-options there.
Remove the key if the chunking behavior is no longer being customized.

Example fix

// before
module.exports = { experimental: { turbopackChunkingHeuristics: true } }
// after
module.exports = { experimental: { turbopackChunking: {} } }

Defensive patterns

Strategy: validation

Validate before calling

if ((config.experimental as any)?.turbopackChunkingHeuristics !== undefined) {
  throw new Error('Rename to experimental.turbopackChunking');
}

Type guard

function noOldHeuristicsKey(exp: any): boolean {
  return exp?.turbopackChunkingHeuristics === undefined;
}

Prevention

Grep for `turbopackChunkingHeuristics` after version upgrades.
Keep experimental Turbopack options grouped under `turbopackChunking`.

When it happens

Trigger: A config containing `experimental: { turbopackChunkingHeuristics: true }` or any value for that key; upgrading Next.js without migrating Turbopack heuristic flags.

Common situations: Version upgrade where the heuristic flag was folded into the new `turbopackChunking` object; stale examples in tutorials.

Related errors

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