vercel/next.js · error

Unexpected cache miss after cache warming phase during prere

Error message

Unexpected cache miss after cache warming phase during prerendering. This is likely caused by non-deterministic arguments that differ between the cache warming phase and the final prerender phase (e.g. unstable array order). Ensure that arguments passed to cached functions are deterministic.

What it means

Error "Unexpected cache miss after cache warming phase during prerendering. This is likely caused by non-deterministic arguments that differ between the cache warming phase and the final prerender phase (e.g. unstable array order). Ensure that arguments passed to cached functions are deterministic." thrown in vercel/next.js.

Source

Thrown at packages/next/src/server/use-cache/use-cache-wrapper.ts:2732

            return makeRuntimeHangingPromise(
              workUnitStore.renderSignal,
              workStore.route,
              'dynamic "use cache"',
              workUnitStore
            )
          }
        // fallthrough
        case 'prerender-runtime':
          if (!cacheSignal) {
            // This is the final prerender (cacheSignal is null), which means
            // all caches should have been warmed during the prospective
            // prerender. A cache miss here indicates that the cache key is
            // non-deterministic (e.g. due to unstable array order in the
            // arguments). Known dynamic keys (e.g. from fallback params) are
            // already handled by the early return above. We return a hanging
            // promise so this becomes a dynamic hole rather than generating a
            // broken cache entry that gets aborted.
            console.warn(
              new Error(
                `Unexpected cache miss after cache warming phase during prerendering. This is likely caused by non-deterministic arguments that differ between the cache warming phase and the final prerender phase (e.g. unstable array order). Ensure that arguments passed to cached functions are deterministic.`
              )
            )
            // This is an anomaly (non-deterministic cache key), so we can't
            // know whether a runtime prerender would resolve it. Treat it as
            // runtime data, conservatively: the cost is at most a redundant
            // runtime prefetch request.
            return makeRuntimeHangingPromise(
              workUnitStore.renderSignal,
              workStore.route,
              'dynamic "use cache"',
              workUnitStore
            )
          }
          break
        case 'prerender-legacy':
        case 'request':

View on GitHub (pinned to 258b1c1bc0)

Solutions

1. Pass deterministic, stably ordered arguments to cached functions so the warming phase and prerender phase produce the same cache keys.

When it happens

Trigger: Thrown at packages/next/src/server/use-cache/use-cache-wrapper.ts:2754 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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