vercel/next.js · error · Error

Route ${workStore.route} used `unstable_navigation()`, which

Error message

Route ${workStore.route} used `unstable_navigation()`, which requires Cache Components to be enabled. Learn more: https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents

What it means

Error "Route ${workStore.route} used `unstable_navigation()`, which requires Cache Components to be enabled. Learn more: https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents" thrown in vercel/next.js.

Source

Thrown at packages/next/src/server/request/cache-stages.ts:187

 * rendering cost.
 *
 * It has no effect during static prerendering — static output is computed
 * once and shared across many clients, so there's no per-request cost to
 * save — and no effect on the initial load of a page.
 *
 * Unlike `connection()`, it does not mark the subtree as request-dependent —
 * content below `await unstable_navigation()` remains fully cacheable.
 */
export function unstable_navigation(): Promise<void> {
  const workStore = workAsyncStorage.getStore()
  const workUnitStore = workUnitAsyncStorage.getStore()

  if (!workStore || !workUnitStore) {
    const callingExpression = 'unstable_navigation'
    throwForMissingRequestStore(callingExpression)
  }
  if (!process.env.__NEXT_CACHE_COMPONENTS) {
    throw new Error(
      `Route ${workStore.route} used \`unstable_navigation()\`, which requires Cache Components to be enabled. Learn more: https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents`
    )
  }

  if (!isRequestApiAllowedInCurrentPhase(workUnitStore)) {
    throw new Error(
      `Route ${workStore.route} used \`unstable_navigation()\` inside \`after()\` while rendering. The \`unstable_navigation()\` function is used to indicate the subsequent code must only run during an actual navigation, but \`after()\` executes after the request, so this function is not allowed in this scope. See more info here: https://nextjs.org/docs/app/api-reference/functions/after`
    )
  }

  switch (workUnitStore.type) {
    case 'prerender': {
      // Static prerenders are computed once and shared across many
      // clients, so there's no per-request prefetch cost to save by
      // deferring the content — it's deliberately included in the static
      // output (and thus in static prefetches).
      // However, it's excluded from the shell, and has to be separated from
      // unstable_prefetch(), so we have to delay it.

View on GitHub (pinned to 258b1c1bc0)

Solutions

1. Enable Cache Components with experimental.cacheComponents: true in next.config.js
2. Remove the unstable_navigation() call from the route
3. Gate the call behind a check that Cache Components is enabled before using navigation-stage APIs

When it happens

Trigger: Thrown at packages/next/src/server/request/cache-stages.ts:175 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of vercel/next.js@258b1c1bc0 (2026-08-21). Data as JSON: /api/errors/44e7d5af11fe1888. Report an issue: GitHub.