
Why 'use cache: private' Isn't Caching in Next.js 16
'use cache: private' never stores anything on the server between requests. In production it only dedupes calls inside one request, and with the default config it re-runs on every client navigation too, no matter what cacheLife says. I built a small Next.js 16.4.6 app this morning, logged every execution, and drove it with a real browser across six configs. Here's what actually got reused, what the stale value really controls, and the two fixes that work.
What Does 'use cache: private' Actually Cache?
Less than the name suggests. The official docs say it plainly, if you read the second sentence: matching calls within one request can reuse the result, but Next.js does not store it in a server cache across production requests. The only thing that outlives the request is the rendered output in the browser's router cache.
So I tested both halves. The function under test reads a cookie, appends a line to exec.log and returns a random token, so a reused result shows the same token:
// lib/data.ts
import { cookies } from 'next/headers'
import { cacheLife } from 'next/cache'
export async function getPrivate() {
'use cache: private'
cacheLife({ stale: 60 })
const sid = (await cookies()).get('sid')?.value ?? 'guest'
logExec('private', sid) // appends a line to exec.log
return { sid, n: Math.random().toString(36).slice(2, 8) }
}The page renders two components that both call getPrivate(), inside a <Suspense>. Then I compared it with a plain 'use cache' function that gets the cookie value as an argument. Production build, next start, curl:
# 3 requests, same cookie (sid=alice), next start
private 1: A alice 9tbgzf B alice 9tbgzf
private 2: A alice pekukm B alice pekukm
exec.log: 2 lines for 2 requests
# 'use cache' with the cookie passed as an argument
public 1: P alice 6eyz0c
public 2: P alice 6eyz0c
exec.log: 1 line for alice, 1 line for bobRequest dedupe works, cross-request caching doesn't exist. Both components got the same token from one execution, and every new request ran the function again. The public version ran once for alice and once for bob, then served both from cache. If you reached for the private directive hoping to cut database load per user, it cuts exactly zero queries across requests.
Why Does It Re-Run on Every Client-Side Navigation?
This is the complaint in vercel/next.js#85672, still open, where people report the function logging on every navigation. I reproduced it. With cacheLife({ stale: 60 }), I clicked from /nav to /private and back at 0, 5 and 40 seconds. Three navigations, three executions, three different tokens.
The reason is the router cache, not the directive. With partialPrefetching unset, a plain <Link> only prefetches the static parts of the route. The private part is fetched at navigation time, and dynamic navigations are kept on the client for staleTimes.dynamic, which has defaulted to 0 seconds since Next.js 15. The stale you set never enters the picture. You do get a hint: next start prints a warning that cacheComponents is enabled without a partialPrefetching option. Most people scroll past it.
I ran the same click script against six setups. "On load" is how many times private functions ran on the server just from loading the page with the links, before any click. The other columns are the return visits.
| Config | Link | On load | +5 s | +40 s | +75 s |
|---|---|---|---|---|---|
partialPrefetching unset (default) | plain | 0 | re-ran | re-ran | - |
staleTimes.dynamic: 30 | plain | 0 | reused | re-ran | - |
partialPrefetching: true | plain | 3 (one per link) | reused | reused | - |
partialPrefetching unset (default) | prefetch={true} | 1 | reused | reused | reused (78 s old) |
staleTimes.dynamic: 30 | prefetch={true} | 1 | reused | reused | reused |
partialPrefetching: true | prefetch={true} | 1 | reused | reused | re-ran |
Only partialPrefetching: true made stale: 60 mean 60 seconds. Every other row was governed by a global number. staleTimes.dynamic: 30 reused the result at 5 seconds and threw it away at 40, overriding my 60. A prefetch={true} link without partial prefetching kept a 78-second-old result, which lines up with the 5-minute staleTimes.static default that the docs apply to full prefetches. With partial prefetching on, the per-link prefetch response carried x-nextjs-stale-time: 60, the result was reused at 40 seconds and refetched at 75. That's the documented behavior, working.
What Does Partial Prefetching Cost on the Server?
The fix isn't free, and that "3 (one per link)" cell is where it shows. With partialPrefetching: true, loading a page that had links to three routes fired one App Shell prefetch per route, and each of those ran the target's cached functions on the server: the 60-second private one, a 10-second private one and the public one. Nobody had clicked anything.
Then the first real click to /private ran the function once more. My reading of the docs is that results with staleunder 5 minutes are left out of the App Shell, so the prefetch rendered it and the shell didn't keep it. Either way the log is the log: four executions to show one page, then free reuse for 60 seconds.
On a nav with 20 links into authenticated routes, that's 20 server renders per page view before the user does anything. If those functions hit a slow API or a metered database, count it. I'd still turn it on, because Next.js says both flags become the default in the next major, but I'd put expensive personalized work behind await prefetch() from next/cache, which keeps that subtree out of the shell and runs it only on a per-link prefetch or the navigation.
The config that worked
// next.config.ts
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
partialPrefetching: true,
}
export default nextConfigKeep stale at 30 seconds or more. The cacheLife reference says anything shorter is excluded from prerenders because a prefetch would expire before the click. My 10-second function re-ran on every visit in every config.
Why Does It Look Cached in next dev?
Because dev does something production doesn't. Five curl requests against next dev: the second response showed the first response's token, the third showed the second's, and so on. Dev keeps private results in memory, keyed by cookies and headers, and serves the previous one while it renders a fresh one in the background. Change a header and you get a fresh result.
The function still ran five times for five requests.So in dev you see repeated timestamps and conclude it's caching, then production shows a new value every time and you think the deploy broke it. Nothing broke. Dev was the odd one out. Count executions against next build && next startbefore you trust any caching claim, including mine. The same "works locally, different on Vercel" trap shows up in the Node 20 deprecation error, for a different reason.
How Do You Cache Per-User Data Across Requests?
Use plain 'use cache'and move the request API out of it. You can't just swap the directive, because the build refuses:
Error: Route "/bad1": `cookies()` can't be read inside `"use cache"`.
Read it outside the cached function and pass what you need as an argument.Do what the error says. The argument becomes part of the cache key:
// read the request API outside, pass the value in
async function Recommendations() {
const sid = (await cookies()).get('sid')?.value ?? 'guest'
const recs = await getRecommendations(sid)
return <List items={recs} />
}
async function getRecommendations(sid: string) {
'use cache'
cacheLife('minutes')
cacheTag(`recs-${sid}`)
return db.recommendations.rank({ sid })
}That's the row in my test that ran once per user and then served every request from cache. Two cautions. First, pass the smallest value that determines the output, like a user ID or plan tier, not the whole session token, or you'll get one entry per login. Second, the default in-memory handler is per instance (my test was one self-hosted process, where it persists), so on serverless you want 'use cache: remote'or a custom handler if hit rate matters. Treat the user ID as an access boundary too: if two users can map to the same argument they'll see the same data. I've written about getting that boundary wrong at the database layer in Supabase table grants.
One more error you'll hit when you first add the private directive: call it in a page without a <Suspense>boundary and the build stops with "Next.js encountered uncached or runtime data during prerendering". Private functions run at request time, so they need a fallback, or export const instant = false if you accept a blocking page.
So When Should You Use 'use cache: private'?
When the data is personal and you only want two things:
- One call per request, even if five components ask for the same thing. React's
cache()also does this, but the directive lets you read cookies inside it. - Instant back-and-forth navigation for that user, with
partialPrefetching: trueand astaleof 30 seconds or more.
If you need fewer database hits across requests, it's the wrong tool. If you're on the default config, you're getting the first benefit and not the second. I'd rather know that from a log file than from a load test. For more on where Next.js fits in an AI stack, see Claude Agent SDK vs Vercel AI SDK.
How I Tested This
Next.js 16.4.6 (the latest tag on November 16, 2026) with React 19.3.1, Turbopack production builds, next start on the Mac mini, and Chromium driven by Playwright with a fixed sid cookie. Each config got a clean .next, a fresh build and a fresh browser context. Executions came from the log file the functions write, not from page output, so a reused render and a re-run can't be confused. The plain-link and prefetch={true}runs used separate pages and separate browser sessions so one couldn't warm the other's cache, which happened in my first attempt and made everything look cached. Timings are from one run per config, so treat the 78-second figure as "at least 78", not an exact limit.
If you're building something like this for a client, the full-stack work I do in Allen, TX is the context for most of these tests.
Next.js App Slower Than It Should Be?
I build and fix production Next.js apps on Vercel. If your caching only works in dev, send me the repo and I'll tell you which layer is actually serving your pages.
Related Posts
Full-Stack
vercel.toml vs vercel.json: What I Found on Real Deploys
I deployed Vercel's new vercel.toml to throwaway projects. Routing matched vercel.json exactly, but both files together fail the deploy, TOML can't hold null (framework = null), and vercel build on CLI < 58 silently drops it.
Full-Stack
Vercel Node.js 20.x Discontinued Error: How to Fix It
Since October 1, 2026 Vercel refuses new builds on Node.js 20. Tested on a throwaway project: engines 20.x, ^20.11.0 and >=18 <21 fail in under a second, >=20 quietly runs Node 24, engines overrides Project Settings, .nvmrc is ignored, and the API still accepts 20.x.
Full-Stack
Vercel Workflow DevKit: Durable AI Agents Guide
Every tool call an agent makes becomes a persisted, retryable step, so a crash, a redeploy, or a pause that lasts weeks resumes exactly where it left off instead of starting over. How DurableAgent, "use step", and createHook actually work — and where n8n still wins.