The Next.js docs tell you that the serializable arguments you pass to a use cache function become part of its cache key. They even list which types are supported. What they don't show is how binary values end up in that key, or what quietly falls out of it. That gap matters, because a cache key is a promise. Two calls with the same key get the same answer, and if the key is missing something, one caller can end up with another caller's result.
So I stopped guessing and tested it. I ran 54 pairs of different inputs through use cache on Next.js 16.4.4, 16.4.5 and 16.4.6, then opened the code that builds the key to find out why the results looked the way they did. Some of it surprised me. Two File objects with the same bytes but different names got the same cache entry. So did a byte array with an odd number of bytes and the same array with one extra zero byte on the end. It lines up with a security advisory Next.js published with the 16.4.5 fix, GHSA-rhh4-g77r-r9qj, and I'll get to that below.
I ran the tests with
next start, the default in-memory cache handler andcacheComponentsset to true, calling cached functions from route handlers and one Server Action page. The demo reproduces with one command (npm run demo) and the rest of the lab takes a few more. The code is in nextjs-use-cache-key-lab.
The short version
If you only have a minute, this is what I found.
- Most inputs behave the way you'd hope. On 16.4.6, 46 of my 54 pairs of different inputs got their own cache entry.
-
Until 16.4.5, two different binary values could share one cache entry. The key ignored a
File's name and type. It treated aBloband aFilewith the same bytes as one value. It also treated a byte array with an odd number of bytes as identical to that array plus one trailing zero byte. 16.4.5 fixed all of that. -
File.lastModifiedstill isn't part of the key, and the source says that's on purpose. For a form upload it's only the time your server parsed the request. - Values the cache can't read (class instances, functions, RegExp, Symbols) share one entry when your function ignores them, and throw when a closure captures them.
-
A
Uint8ArrayorBlobargument over about 250,000 bytes throwsRangeError: Maximum call stack size exceeded, and the exact threshold depends on your machine. I found the line of code behind it, and it reproduces in plain Node.
What goes into a Next.js use cache key
The docs list the parts of a use cache key. There's the build ID (or your deploymentId if you've set one, which overrides it), a function ID, the serializable arguments you pass, and in development an HMR hash. Variables your function captures from an outer scope are bound as arguments too, so they count as well. If you're new to all of this, my Next.js 16 Cache Components migration guide covers the basics, and the official use cache docs are the reference.
The build ID and the function ID aren't interesting. They're the same for every call of the same function in the same build. The arguments are where the surprises live, so that's what I tested.
How I tested the use cache key
The idea is simple. For each case I build two values that differ in exactly one way. Then I call the same cached function with value A, with A again (a control, to prove the call really is cached), and finally with value B. The function returns a fresh marker every time it actually runs. In my harness that's a random token, and in the short examples below it's a timestamp. If B gets A's marker back, B reused A's cache entry.
Sharing an entry isn't always a problem, though. I also compute what B should have seen without any cache. That separates a harmless alias from a wrong answer.
| Status | Meaning |
|---|---|
| SEPARATE | B got its own entry |
| SHARED | B reused A's entry, and the output is what B would have produced anyway |
| SHARED-WRONG | B reused A's entry and received output computed for a different input |
I ran this on three versions on my machine, 16.4.4, 16.4.5 and 16.4.6. Across those three the results change at exactly one boundary, between 16.4.4 and 16.4.5. If turning on cacheComponents breaks your own build before you can even test this, I wrote up the errors I hit in Every Way I Could Break Next.js Cache Components.
The repo also holds reference results for 12 versions (16.0.0 to 16.4.6, plus Node 20 and 24 for two of them). They come from a second machine, not mine. In those, the key results are identical on every version up to 16.4.4, and identical on 16.4.5 and 16.4.6. I didn't run the other versions myself, so I treat that as supporting data and not as part of my own test.
The results
Read the bold rows first.
| What differs between A and B | 16.4.4 | 16.4.5 and 16.4.6 |
|---|---|---|
Strings, numbers, booleans, BigInt, null vs undefined, 0 vs -0, '1' vs 1, undefined vs the string '$undefined'
|
SEPARATE | SEPARATE |
Object values, nested values, [1,2] vs [2,1], an array vs an object with numeric keys, {} vs []
|
SEPARATE | SEPARATE |
Object key order swapped ({a, b} vs {b, a}) |
SEPARATE | SEPARATE |
| Map, Set and FormData insertion order swapped | SEPARATE | SEPARATE |
| Date, Map and Set values, FormData, URL, URLSearchParams | SEPARATE | SEPARATE |
| Typed arrays with different bytes, only the last byte of 200,000, Uint8 vs Int8, Uint8 vs ArrayBuffer, Uint8 vs Buffer | SEPARATE | SEPARATE |
| Blob or File with different bytes, only the last byte of 200,000 | SEPARATE | SEPARATE |
Array hole [1,,3] vs [1, undefined, 3]
|
SHARED (harmless) | SHARED (harmless) |
| Same 4 bytes as a standalone array vs a view into a bigger buffer | SHARED (harmless) | SHARED (harmless) |
| File name differs (same bytes) | SHARED-WRONG | SEPARATE |
| Blob or File type differs (same bytes) | SHARED-WRONG | SEPARATE |
| Blob vs File (same bytes) | SHARED-WRONG | SEPARATE |
Odd-length binary value vs the same value plus one trailing 0 byte (Uint8Array, Blob, File) |
SHARED-WRONG | SEPARATE |
File.lastModified differs |
SHARED-WRONG | SHARED-WRONG |
| Class instance, function, RegExp or Symbol that the function ignores | SHARED | SHARED |
The totals are 38 SEPARATE, 7 SHARED and 9 SHARED-WRONG on 16.4.4, and 46 SEPARATE, 7 SHARED and 1 SHARED-WRONG on 16.4.6. The full 54-row table is in the repo.
Bob gets Alice's file
The easiest way to see the problem is a tiny cached function that takes a File.
// lib/inspect.js
"use cache";
export async function inspectUpload(file) {
return {
name: file.name,
type: file.type,
size: file.size,
filledAt: Date.now(),
};
}
I call it with two Files that hold the same 32 bytes but have different names. This is real output from my run on 16.4.4.
inspectUpload(File "alice.pdf") -> { "name": "alice.pdf", ... "filledAt": 1794584074839 }
inspectUpload(File "bob.pdf") -> { "name": "alice.pdf", ... "filledAt": 1794584074839 }
Look at the second line. Bob's call got Alice's result. The filledAt value is identical, so the function body never even ran. On 16.4.5, Bob gets bob.pdf, as you would expect.
The byte-level case is stranger. Take this function.
export async function describeBytes(bytes) {
return {
length: bytes.length,
last: bytes[bytes.length - 1],
filledAt: Date.now(),
};
}
On 16.4.4, describeBytes(Uint8Array.from([61, 62, 63])) returns length: 3, which is correct. Then I call describeBytes(Uint8Array.from([61, 62, 63, 0])), a different array with four bytes. It also returns length: 3. On 16.4.5 it returns length: 4.
One caveat before I go on. The docs list TypedArrays and ArrayBuffers as supported arguments, but they don't mention Blob or File. So what I report for those two is observed behaviour in the versions I tested, not a documented guarantee.
One extra zero byte, and the cache couldn't tell the difference.
Does the use cache File bug happen through a real form upload?
Everything above calls the cached function from a route handler. In a real app a File usually arrives through a Server Action, so I tested that path too. It's a plain <form action={upload}>, where the action takes formData.get('file') and passes it to the same cached inspectUpload. I posted the form the way a browser without JavaScript would. I wrote about other Server Action problems in Next.js 16 Server Actions and the bugs that only show up in production.
The result was the same. On 16.4.4 the bob.pdf upload returned alice.pdf's result, and a 4-byte file returned the result for the 3-byte file before it. On 16.4.5 each upload got its own result. Inside the action the value was a real File. You can run it with npm run action.
Why this happens
The code that builds the key lives in Next's server bundle, not in your code. Your arguments go through React's reply encoder first. When one of them holds binary data, the result is a FormData, and a function called encodeFormData turns that into the string used in the key. You can read it in node_modules/next/dist/server/use-cache/use-cache-wrapper.js in all three versions I tested, and my diagnose script also prints the minified copy from the build output. What follows is a simplified, renamed copy of the binary branch of encodeFormData as it was in 16.4.4, the last version before the fix. It's not a drop-in copy of Next's key builder. The diagnose output in the repo's reference results shows the same fields missing from the key in every build from 16.0.0 to 16.4.4, but I didn't run those versions myself.
async function encodeFormData(formData) {
let key = "";
for (const [field, value] of formData) {
let text;
key += field.length.toString(16) + ":" + field;
if (typeof value === "string") {
text = value;
} else {
const buf = await value.arrayBuffer();
text =
buf.byteLength % 2 === 0
? String.fromCodePoint(...new Uint16Array(buf))
: String.fromCodePoint(
...new Uint16Array(buf, 0, (buf.byteLength - 1) / 2),
) +
String.fromCodePoint(new Uint8Array(buf, buf.byteLength - 1, 1)[0]);
}
key += text.length.toString(16) + ":" + text;
}
return key;
}
Here's what that means. The bytes become a string, two bytes at a time, and that's all that goes into the key for that argument. There's no name, no type, and no record of whether it was a Blob or a File. On top of that, an odd number of bytes ends with a lone byte, which gets read as one code unit. On a little-endian CPU (x86 and, in practice, ARM) that's the same code unit you get from reading [x, 0] as a 16-bit number. So [61, 62, 63] and [61, 62, 63, 0] produce the same string with the same length. Replaying the logic shows that even-length arrays don't collide this way. Adding a zero byte to an even-length array makes it odd-length, and an odd-length array gets its lone byte appended as an extra code unit, so the two strings differ. My lab tests the 3-byte and 4-byte case, so the even-length part comes from reading the code and not from a run.
From 16.4.5 the binary branch also writes the name, the type and the byte length before the text.
key +=
"B" +
value.name.length.toString(16) +
":" +
value.name +
value.type.length.toString(16) +
":" +
value.type +
buf.byteLength.toString(16) +
":" +
text;
Reading minified code is one thing, but I also wanted to see the real keys, so I wrote a small cache handler that wraps Next's default one and logs every key it receives. This is output from my run. The hex ids differ per build, so compare the two lines inside one version.
16.4.4 alice.pdf 1:110:܇܇܇܇܇܇܇܇܇܇܇܇܇܇܇܇1:050:["c084f7f0…",["$B1"],["VTD4as…"]] miss
16.4.4 bob.pdf 1:110:܇܇܇܇܇܇܇܇܇܇܇܇܇܇܇܇1:050:["c084f7f0…",["$B1"],["VTD4as…"]] HIT, same string
16.4.5 alice.pdf 1:1B9:alice.pdf0:20:܇܇܇܇܇܇܇܇܇܇܇܇܇܇܇܇1:050:["c02d82da…",["$B1"],["noVPW1…"]]
16.4.5 bob.pdf 1:1B7:bob.pdf0:20:܇܇܇܇܇܇܇܇܇܇܇܇܇܇܇܇1:050:["c02d82da…",["$B1"],["noVPW1…"]]
The odd character is U+0707. My 32 bytes, each with the value 7, are read two at a time as sixteen 16-bit code units. On 16.4.4 the two keys are the same string, so the second call is a hit. On 16.4.5 the file name is in the key. The same experiment for [61,62,63] and [61,62,63,0] shows 0:3: against 0:4: on 16.4.5, which is the byte length that 16.4.4 left out. You can run it yourself with npm run keys.
That one change explains every row that flipped. It also explains why lastModified didn't flip, because it isn't in that line. You can print this function from your own build with npm run diagnose, so you don't have to take my word for it.
Is this the use cache cross-user cache disclosure advisory?
It matches. Next.js's November 3 security release lists Cross-user cache disclosure and poisoning through binary use cache arguments. The GitHub advisory for it (GHSA-rhh4-g77r-r9qj, CVE-2026-119349) is rated Moderate there, while the release post says Medium. It lists 16.0.0 through 16.4.4 as affected and 16.4.5 as the fix. It says that applications passing binary arguments "(such as Uint8Array or Blob values)" to use cache functions "can produce identical cache keys for distinct arguments".
My results line up with that. On 16.4.4 I got identical key strings for different File and Uint8Array values, and shared results for Blob values too (I didn't print the Blob keys). The key function changed in 16.4.5. I only ran 16.4.4, 16.4.5 and 16.4.6 myself, so the rest of the affected range is the advisory's word and not my measurement. I didn't try to exploit anything. What my lab shows is incorrect cache reuse, and how exposed you are depends on your app and your cache handler.
Does this affect your app?
The advisory is careful about this, and you should be too. It says the risk applies when an application uses binary arguments "to distinguish users or accounts", the remaining cache-identity inputs match, and the entries are shared across callers. It adds that this "does not permit arbitrary access to unrelated cache entries."
In my tests the practical version is that a collision needs a function whose output depends on something the key ignored. This specific collision doesn't apply to functions that take only strings and numbers. The concern is when distinct binary values change what the function returns but the key treats them as the same. If you pass a File and return something derived from its name or type, or you identify a user with a byte array, upgrade to 16.4.5 or later. The docs also say that with the default in-memory handler, entries typically don't persist across serverless requests, and hosts can replace the cache handler. So your exposure depends on where you host.
The same security release has other use cache advisories, for nested functions and for unstable_cache. They are different bugs and this article doesn't cover them.
There's one more thing if you run old versions. A separate advisory (GHSA-673q-mjm6-r5xr, Critical, no CVE) describes unauthenticated remote code execution in App Router apps with Cache Components that have a use cache function returning multiple typed arrays. It affects 16.0.0 through 16.4.0, it's fixed in 16.4.1, and the advisory says there's no known workaround. The three versions I tested aren't in that range and my lab doesn't trigger it. It's still a good reason not to run old versions anywhere reachable from the internet.
Is File.lastModified part of the use cache key?
No, and that looks deliberate. Two Files with the same bytes, name and type but different lastModified share one entry on 16.4.6. The second caller receives the first caller's value.
The readable source that ships with 16.4.5 and 16.4.6 (next/dist/server/use-cache/use-cache-wrapper.js) has a comment next to the key builder. It says the name and type are part of the key because the cached function observes them. It also says "lastModified is excluded", and that it "defaults to the construction time and does not survive multipart submission."
I checked the second half of that comment in the lab's Server Action test on 16.4.6. I uploaded a file with lastModified set to 1000, and the action saw the server's current time instead. A File you build without that option also gets the current time as its lastModified, and the MDN page for the File constructor documents the option. So for form uploads, lastModified is when your server parsed the request. Don't read it inside a cached function and expect the date from the user's file.
What about values the cache can't read?
The docs say you can pass non-serializable values "as long as you don't introspect them". I wanted to know what that means in practice, so I tested two situations. One is passing the value as an argument. The other is capturing it in a closure inside the cached function.
| Value | Passed as an argument (the function never reads the opaque ones) | Captured by a closure inside the cached function |
|---|---|---|
| Class instance | one shared entry | throws |
| Function | one shared entry | throws |
| RegExp | one shared entry | throws |
Symbol('a') |
one shared entry | throws |
Symbol.for('a') |
one shared entry | one shared entry if only mentioned, throws if read |
| Date, Map, Set, plain object | separate entries | separate entries |
One shared entry means that, for example, Symbol.for('a') and Symbol.for('b') get the same cached result. That's by design, since the function isn't supposed to read them. It's still worth knowing, because it means these values never affect the key. The errors are the generic Flight ones. One example is "Only plain objects, and a few built-ins, can be passed to Client Components from Server Components. Classes or null prototypes are not supported." Reading a captured Symbol.for logs "Cannot access constructor on the server" on the server.
One more oddity. The docs list URL instances as unsupported, but a URL worked as an argument in my tests. It arrived inside the function as a string, and different URLs got separate entries. I wouldn't rely on that.
Cache misses you create without noticing
Now the opposite problem. These all got separate entries, which is correct, but each one is a potential extra miss.
- An object with its keys in a different order is a different entry.
- Map, Set and FormData insertion order matters.
-
0and-0are different, and so arenullandundefined. - An object with a shared reference is different from two equal copies.
Nothing here is a bug. If you build argument objects in different places, pass primitives like an id or a string instead and let the function look the rest up.
What is the maximum argument size for use cache?
A binary argument over a certain size throws.
RangeError: Maximum call stack size exceeded
On my machine the largest Uint8Array that works in a fresh process is 250,871 bytes. At 250,872 it throws, though the threshold moves a little as the process warms up, as you will see below. On a second machine the same test stopped at about 247,000, so the exact number depends on your machine and Node version, and I'd treat anything near 250,000 as the edge.
Blob fails at about the same size (I didn't measure File separately). Typed arrays fail at about the same number of bytes whatever their element type, which is 125,435 elements for Uint16Array and 31,358 for Float64Array. Across the three versions I ran, the Uint8Array limit never changed, but the others moved by a few dozen bytes. Uint16Array was 125,447 on 16.4.4 and 16.4.5 and 125,435 on 16.4.6, and Blob measured 250,895 in one run and 250,871 in another. So read these numbers as "about", not exact.
The cause looks like the String.fromCodePoint(...new Uint16Array(buf)) line from earlier. As the MDN page for String.fromCodePoint shows, it takes its input as separate arguments, so the spread passes one function argument per two bytes, and each argument takes a slot on the call stack. Two things back this up.
-
It reproduces without Next.js.
String.fromCodePoint(...new Uint16Array(n))in plain Node fails above about 125,235 elements. - It moves with warm-up. On a fresh process 250,872 bytes failed. After 300 other requests the same size passed, and the warmed-up maximum was 250,899.
The lab also has a --stack-size experiment. I haven't run it on my own machine, so I'm not making a claim about it. In the reference run from the second machine the limit roughly halved at --stack-size=500 and roughly doubled at 2000, which fits the stack explanation, but that isn't my own measurement.
So there's no exact number to memorise. Treat about 240 KB as the ceiling on a default stack, and stay far below it. And please don't raise --stack-size in production to dodge this. Pass less.
Buffers and strings have a separate limit. A Node Buffer fails at exactly 1,000,000 bytes and a string at about 999,930 characters, with a different error. The message is "Maximum array nesting exceeded. Large nested arrays can be dangerous. Try adding intermediate objects." It comes from React's Flight decoder, which has a default arraySizeLimit of 1e6. I didn't trace why Buffers and strings count against it. In the reference results from the second machine, this limit is absent on 16.0.0 and 16.1.0 and present from 16.1.7. I haven't run those versions myself.
So what would I actually do?
-
Upgrade to 16.4.5 or later if you pass binary values to
use cacheat all. - Pass ids, not files. Store the upload, pass its id (a string), and read the bytes inside the cached function. The id must change when the content changes, and a content hash or a version number works. If you reuse one id for edited content, the cache will happily return the old result. A sketch follows.
export async function analyze(fileId) {
"use cache";
const bytes = await storage.read(fileId); // read inside the cache
return expensiveAnalysis(bytes);
}
- Never use a binary value as a user or account identifier in a cached function's arguments.
- Keep arguments small. My rule of thumb is to stay under about 100 KB, which leaves a wide margin below the limit.
-
Pass only the metadata your function reads, and not
File.lastModifiedfrom a form upload. On 16.4.4, passingname,typeandsizeas separate arguments stopped the name, type and trailing-byte collisions I found (npm run workaround). ThelastModifiedcase stayed shared until I passed it too. On 16.4.5 and later those three are already in the key.lastModifiedisn't, and for a file that came through a multipart form it's the time your server parsed the request, so passing it as an argument can create unnecessary cache misses on every upload. If you need a modified date, send it as a separate form field. - Pass primitives rather than objects you build in different places.
What I didn't test
I'd rather tell you where my results stop than let you find out the hard way.
- A second cache handler (Redis,
use cache: remote) oruse cache: private. - Page and component renders. I called cached functions from route handlers and from one Server Action.
-
next dev, and runtimes other than Node. - Even-length byte arrays with a trailing zero. The code says they don't collide, but my lab only runs the 3-byte against 4-byte case.
- Versions other than 16.4.4, 16.4.5 and 16.4.6. The repo's reference results cover 12 versions, but they come from a second machine and not from me.
- Next.js 15.x. The release post says 15.5.29 got patches in the same release, but I only tested 16.x, so I make no claim about 15.
- Other operating systems and Node versions. My own runs used one setup, and the second machine matched on the key results.
- I read the compiled JavaScript that ships in each version, not Next's TypeScript source.
Run it yourself
The repo has the tests and the reference results, so you can check any of this yourself. It takes a few commands.
git clone https://github.com/shubhrapokhariya/nextjs-use-cache-key-lab.git
cd nextjs-use-cache-key-lab
npm run demo # the two examples above (the first run installs Next.js, so it takes a while)
npm run quick # 54 input pairs on 16.4.4, 16.4.5, 16.4.6
npm run summarize
npm run diagnose # prints the key function from your own build
npm run keys # prints the real cache keys for the alice/bob and trailing-zero cases
npm run action # the same bug through a Server Action with a form upload
npm run workaround # which extra arguments avoid which collisions
npm run limits # the size experiments
npm run quick tests three versions. npm run full tests all 12 and takes much longer. The limits script includes the optional stack-size experiment, and the README shows how to skip it if it fails on your machine. The lab installs old Next.js versions that have known security advisories, so run it on a throwaway machine and not on a server.
The 54 input pairs are in template/app/lib/cases.js. If you find a case that behaves differently on your machine, I'd really like to know.
Next.js ships often, so I'll update this post if the behaviour changes.
Over to you
- Do any of your
use cachefunctions take aFile, aBlobor a byte array? Which ones would you check first? - Has
use cachesurprised you with an argument type, or a key behaviour I didn't test?
Leave a comment if you've seen something similar. If you find an input pair the lab doesn't cover, feel free to open an issue on the repo with the two inputs and your Next.js version. I'd be happy to take a look.
Top comments (3)
If you're passing a File to a use cache function, consider passing an ID instead and reading the file inside the cached function.
The ID needs to change when the file content changes. A content hash or version number can work for this. Otherwise, the cache may return a result based on the old file content.
Wait, Bob actually gets Alice's file result? That's quite a bug 😄 It's crazy how one small detail missing from the cache key can lead to something like this. Also, really interesting to see how you tested it across different versions, Shubhra 😀
Thank you so much, Hema! 😊 Yes, Bob actually got Alice's cached result because the cache key ignored the file name and type. The two files had the same bytes, so they ended up sharing the cache entry. Thankfully, this was fixed in 16.4.5. 😄 Thanks for reading and sharing your thoughts!