vercel/next.js · error

`experimental.useCache` cannot be disabled when `cacheCompon

Error message

`experimental.useCache` cannot be disabled when `cacheComponents` is enabled, because Cache Components relies on the `"use cache"` directive. Please remove it from ${configFileName}.

What it means

Thrown at config.ts:1615 when `experimental.useCache` is explicitly set to a falsy value (`false`) while the top-level `cacheComponents` option is enabled. Cache Components internally relies on the `"use cache"` directive, so disabling `useCache` would leave every cached function uncompilable. The fix is to remove the `experimental.useCache` override.

Source

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

    process.env.__NEXT_EXPERIMENTAL_MCP_SERVER === 'true'
  ) {
    result.experimental.mcpServer = true
  }

  if (result.cacheComponents) {
    // TODO: remove once we've finished migrating internally to cacheComponents.
    result.experimental.ppr = true
  }

  // `experimental.useCache` is deprecated in favor of the top-level
  // `cacheComponents` option. A defined value means the user set the option
  // explicitly, because it's only backfilled from `cacheComponents` below.
  if (result.experimental.useCache !== undefined) {
    // Disabling the directive that Cache Components is built around leaves the
    // app in a state where every `"use cache"` fails to compile with an error
    // that asks for the already-enabled `cacheComponents` option.
    if (!result.experimental.useCache && result.cacheComponents) {
      throw new Error(
        `\`experimental.useCache\` cannot be disabled when \`cacheComponents\` is enabled, because Cache Components relies on the \`"use cache"\` directive. Please remove it from ${configFileName}.`
      )
    }

    if (!silent) {
      if (result.cacheComponents) {
        Log.warnOnce(
          `\`experimental.useCache\` is no longer needed, because \`cacheComponents\` already enables the \`"use cache"\` directive. You can remove it from ${configFileName}.`
        )
      } else {
        Log.warnOnce(
          `\`experimental.useCache\` is deprecated. Please use the top-level \`cacheComponents\` option instead in ${configFileName}.`
        )
      }
    }
  }

  // "use cache" was originally implicitly enabled with the cacheComponents flag, so

View on GitHub (pinned to 0ae8c72462)

Solutions

1. Remove the `experimental.useCache` line from your config — `cacheComponents: true` enables the directive for you.
2. If you genuinely do not want Cache Components, set `cacheComponents: false` instead of disabling `useCache`.

Example fix

// before
module.exports = { cacheComponents: true, experimental: { useCache: false } }
// after
module.exports = { cacheComponents: true }

if (config.cacheComponents && config.experimental?.useCache === false) {
  throw new Error('Remove experimental.useCache when cacheComponents is enabled');
}

function consistentCacheFlags(c: any): boolean {
  return !(c.cacheComponents === true && c.experimental?.useCache === false);
}

When it happens

Trigger: `{ cacheComponents: true, experimental: { useCache: false } }`; setting `useCache: false` explicitly while opting into Cache Components.

Common situations: Carrying over an old `useCache: false` from when the feature was experimental; toggling flags independently without realizing the dependency; partial migration to `cacheComponents`.

Related errors

• `experimental.cachedNavigations` requires `cacheComponents`
• `experimental.turbopackGenerateComponentChunks` has been mov
• `experimental.turbopackChunkingHeuristics` has been renamed
• `forbidden()` is experimental and only allowed to be enabled
• `unauthorized()` is experimental and only allowed to be used

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