Allow request APIs inside "use cache: private" in Route Handlers #98549

Goals

1. Allow runtime request APIs (cookies(), headers(), searchParams) inside a 'use cache: private' scope in Route Handlers, the way they are already allowed in Server Components, instead of throwing E178.
2. Give Route Handlers a first-party way to deduplicate request-scoped work — session/auth resolution above all — which today has no supported mechanism at all.
3. Close the open question that is already written into the implementation as a TODO.

Non-Goals

1. Changing non-private "use cache" semantics. It should keep rejecting request APIs everywhere; that restriction is correct.
2. Making React cache() work outside the component tree. That is a different ask, raised in Allow react cache to work on route handle and server actions #53489.
3. Storing private results on the server across requests, or any change to cacheLife / cacheTag semantics.

Background

Route Handlers have no supported request-scoped memoization today.

The natural reach is React cache(), and it is inert there. React's own caveats say cache "is for use in Server Components only," and that calling a memoized function outside a component "will still evaluate the function but not read or update the cache." The Next.js caching docs agree: memoization "doesn't apply to fetch requests in Route Handlers as they are not a part of the React component tree." Consistent with that, packages/next/src/server/route-modules/app-route/module.ts does not reference React at all — there is no dispatcher for cache() to find, so it silently degrades to a pass-through with no warning.

Worth flagging separately: the Authentication guide defines export const verifySession = cache(async () => {...}) and then says you can invoke it "in your data requests, Server Actions, Route Handlers", with a Route Handler example calling await verifySession(). The after() docs similarly say "You can use React cache to deduplicate functions called inside after." Both point users at something that no-ops in a Route Handler. That is a docs bug worth fixing regardless of what happens with this proposal.

The cost is not theoretical. On one app on 16.3.4, an auth wrapper resolves the caller once, and then every service-layer call inside the handler re-resolves it because the cache() wrapper does nothing. Counted by driving the real route modules: a single GET performed 3 session decrypts and 3 identical permission-user database queries where one of each was needed. Every auth SDK I checked (Auth.js v5, @auth0/nextjs-auth0 v4, @supabase/ssr, Clerk's auth()) re-resolves per call and relies on the caller not calling twice — so this multiplies quietly across any app with a service layer.

"use cache: private" reads like exactly the right primitive. Its docs describe request-scoped reuse — "In production, matching calls within one request can reuse the same result, but Next.js does not store it in a server cache across requests" — list cookies(), headers(), and searchParams as allowed, and explicitly name this use case: "If a function only needs request-scoped deduplication, use cacheLife({ stale: Infinity }) to keep it from lowering the route's stale time."

But it throws in a Route Handler, and the implementation carries the open question:

// packages/next/src/server/route-modules/app-route/module.ts
if (workUnitStore) {
  switch (workUnitStore.type) {
    case 'cache':
    case 'private-cache':
      // TODO: Should we allow reading cookies and search params from the
      // request for private caches in route handlers?
      throw createRouteHandlerRequestInUseCacheError(store.route, expression)

(Still present on main; verified as E178 in a 16.3.4 install.)

Alternatives, and why they don't cover this. unstable_cache and "use cache" are cross-request and reject request APIs by design, and cache keys and tags are stored in plain text — inappropriate for anything session-derived. The E178 guidance to "read and resolve request data outside the cached function, then pass only the values you need as arguments" is the thing "use cache: private" exists to avoid. That leaves wrapping the handler in an AsyncLocalStorage scope — which is what Clerk ships, what Next.js runs on internally, and what the after() docs demonstrate for per-request context — or threading the value by hand. Both are workarounds for something the platform nearly supports already.

Proposal

Answer the TODO in the affirmative: allow runtime request APIs inside a 'use cache: private' scope in Route Handlers, matching Server Component behaviour, and keep throwing for 'cache' and 'unstable-cache'.

switch (workUnitStore.type) {
  case 'cache':
  case 'unstable-cache':
    throw createRouteHandlerRequestInUseCacheError(store.route, expression)
  case 'private-cache':
    // allowed: private results are request-scoped and never stored
    // in a server cache across requests
    break

The safety argument for the existing restriction is that request-derived values must not leak into a cache shared across requests. That argument does not apply to private-cache, which by definition is not stored across requests — which is presumably why the same access is already permitted in Server Components.

Two smaller things that would help either way:

• If the answer is yes, the "use cache: private" page could state that Route Handlers are supported; it currently doesn't mention them in either direction, so today the only way to learn the answer is to hit E178 or read module.ts.
• If the answer is no, documenting the reasoning on that page would save people the same detour — and the Authentication guide and after() docs should stop recommending cache() for Route Handlers, since it silently does nothing there.

Happy to validate a canary against a real application with a service layer and measure the before/after, if that's useful.