Let a "use cache" function return a value without storing it

[mhmd-sdghn]

Goals

1. Give a "use cache" function a way to say "return this result to the caller,
   but don't cache it", decided after the work is done, since that's often the
   only point where you can tell.
2. Avoid the redundant second fetch that's currently the only way to get such a
   result back to the caller.
3. Keep the decision inside the cached function, where the response is, instead of
   pushing it out to callers who'd have to guess.

Non-Goals

1. Changing how errors are redacted across a Server Components boundary in
   production. That behaviour is correct and we're not asking for it to change.
2. Caching responses that shouldn't be cached. The opposite, we want a clean way
   to decline.
3. Cache control from outside the function, or per-request opt-outs. This is about
   a function declining its own result.
4. Any change to cacheLife / cacheTag semantics.

Background

We use "use cache" (with cacheComponents: true, Next.js 16.3.1, Turbopack) to
cache proxied GET responses from upstream services. The cached function fetches
upstream and returns the response.

The catch is that whether a response is cacheable is only knowable after the
fetch resolves. We reject a response if it isn't a 200, if it carries
Set-Cookie, if Cache-Control says private or no-store, or if Vary
mentions authorization or cookie all of which mean it's specific to one
client and must never be served to another.

Today, throwing is the only way a "use cache" function can signal outward. That
works for preventing the cache write, but the thrown value doesn't survive:

An error occurred in the Server Components render. The specific message is
omitted in production builds to avoid leaking sensitive details. A digest
property is included on this error instance which may provide additional
details about the nature of the error.

So the caller can't tell "this response is fine but not cacheable" from "the fetch
failed." We tried carrying a custom Error subclass through, and separately a
deterministic nonce in the message neither survives. Only err.digest is left,
and it isn't attributable back to a specific thrown value without a side channel.

The result is that every rejected-but-successful response costs a second, uncached
fetch just to get the body back to the client. It also double-counts our
request-duration metrics, since both fetches are measured.

Alternatives we considered

• Check storability before entering the cached scope. Doesn't work: the check
  needs the response, so this means fetching outside the cache first which costs
  every cache hit a wasted fetch instead of every rejection costing one. Strictly
  worse, since hits dominate.
• Recover the reason from err.digest. Not attributable to a specific throw
  without maintaining a side channel, which defeats the point.
• Cache the rejection with a very short cacheLife. Still caches something we
  explicitly must not cache, and doesn't return the body.
• Give up and never cache the endpoint. What we'd do if the rejection rate were
  high. It's currently low enough that the second fetch is an acceptable cost but
  it's a cost with no way out, which is why we're raising it.

Minimal reproduction

async function fetchAndCache(url: string) {
  "use cache";
  cacheLife({ revalidate: 60 });

  const res = await fetch(url);

  // Only knowable here, after the fetch, inside the cache scope.
  if (!res.ok) {
    throw new Error("NON_STORABLE:" + res.status);
  }

  return { status: res.status, body: await res.text() };
}

export async function GET() {
  try {
    return Response.json(await fetchAndCache(UPSTREAM_URL));
  } catch {
    // In dev, the message above is intact. In a production build it's redacted,
    // so there's no way to know this was the storability throw rather than a
    // network failure or to recover the body that was already fetched.
    // The only option left is to fetch the same URL again.
    const res = await fetch(UPSTREAM_URL);
    return Response.json({ status: res.status, body: await res.text() });
  }
}

Run against a production build (next build && next start) with an upstream that
returns a non-200. Note that this doesn't reproduce under next dev, and a mocked
unit test won't reproduce it either the redaction only happens in a production
build, which makes it easy to write a "fix" that looks like it works.

Proposal

A call available inside a "use cache" function that suppresses the cache write
for that invocation while letting the return value through normally:

import { unstable_dontCacheThisResult } from "next/cache"; // name TBD

async function fetchAndCache(url: string) {
  "use cache";
  const res = await fetch(url);

  if (!res.ok) {
    unstable_dontCacheThisResult();
  }

  return { status: res.status, body: await res.text() };
}

Semantics we'd expect:

• The return value reaches the caller unchanged.
• Nothing is written to the cache for that key, and any existing entry is left
  alone rather than overwritten.
• Calling it more than once, or alongside cacheLife / cacheTag, is harmless,
  suppression wins.
• Calling it outside a "use cache" scope throws, in the same spirit as the
  existing cache APIs.

An alternative shape, if a side-effecting call inside the scope is unappealing:
allow the function to return a wrapper the runtime unwraps, e.g.
return dontCache(value). We'd be happy with either; the call reads better at the
point of decision.

Contributing: Yes, I'd like to implement this. I'm familiar with the caller
side of "use cache" but not with the internals that decide whether a cache entry
gets written, so a pointer to where the write happens and which tests to extend
would get me moving. I'm also happy to defer entirely on the API name and shape; if
maintainers prefer the wrapper form, or a different name, I'll build whichever you
land on.

[icyJoseph]

Hiyo — I do believe something like the snippet at the bottom should work for you.

What'll happen here is that, you'd, most likely, initially get the Not OK result (logs: false 500).

Eventually visiting /api with GET requests, will succeed, and you get the All good result. Further visits print no logs anymore.

After 60 seconds, the cache entry is rerun, and that may hit the Not OK — most likely result — and visiting /api, prints the Not OK payload, with logs printed on every visit.

Once again, eventually, the unstable request succeeds, and we are back on the All good result for another 60 seconds.

The one caveat I found here is tag based revalidation. I had initially done revalidateTag('unstable', 'max'), and was not able to see the Not OK result. That's because, after revalidating tag with a profile like 'max', if the new entry has expire: 0 (from the Not OK branch), it is not stored in the cache, the previous OK result is kept to allow for state-if-error kind of patterns.

However, revalidateTag('unstable', { expire: 0 }) does the trick, and now the cache handler does accept the Not OK branch once again.

// app/api/route.ts
import { cacheLife, cacheTag, revalidateTag } from "next/cache";
import { NextResponse } from "next/server";

async function foo() {
  "use cache";
  const res = await fetch("https://httpbin.dev/unstable?failure_rate=0.9");
  cacheTag("unstable");

  console.log(res.ok, res.status);
  if (!res.ok) {
    cacheLife({ expire: 0 });
    return { status: "Not OK", timestamp: new Date().getTime() };
  }

  cacheLife({ revalidate: 60 });

  return { status: "All good", timestamp: new Date().getTime() };
}

export async function GET() {
  return NextResponse.json(await foo());
}

export async function POST() {
  revalidateTag("unstable", { expire: 0 });

  return NextResponse.json({ done: "ok" });
}

What do you think? I guess you might have already tried these, but found some issue still?

[mhmd-sdghn]

Thank you, this unblocks me. Returning the value and marking the branch with
cacheLife({ expire: 0 }) instead of throwing removes the reason I was double-fetching:
no throw means no error crossing the "use cache" boundary, so nothing is redacted and
the already-materialised body reaches the caller.

For context, the shape I'm applying it to — a route that proxies an upstream, where only
the response tells you whether it may be stored:

async function proxy(path: string) {
  "use cache";
  cacheTag(`proxy:${path}`);

  const res = await fetch(`https://upstream.example.com/${path}`);
  const body = await res.text();

  // Only knowable now: 200, no Set-Cookie, no `Cache-Control: private`.
  if (!isStorable(res)) cacheLife({ expire: 0 });
  else cacheLife({ revalidate: 60 });

  return { status: res.status, body };
}

That works. Two things still argue for a named primitive, and the first I think is worth
addressing either way.

1. The skip lives in the default handler, not the framework

use-cache-wrapper.js calls cacheHandler.set() unconditionally. The decision to drop an
expire: 0 entry is made inside the default handler:

// server/lib/cache-handlers/default.js — set()
if (!process.env.__NEXT_DEV_SERVER && entry.expire === 0) {
  debug?.('set', cacheKey, 'skipped dynamic entry');
  return;
}

So "don't store this" is a convention every custom cacheHandlers implementation has to
discover and reimplement. It isn't always a harmless no-op either — in a Redis-backed
handler, EX: 0 is an error rather than a skipped write:

async set(cacheKey, pendingEntry) {
  const entry = await pendingEntry;
  if (!entry.expire) return; // required; otherwise EX: 0 is a failed round-trip
  await client.set(cacheKey, serialize(entry), { EX: entry.expire });
}

There's a data-handling angle too. In the example above, the branch I'm rejecting is
exactly the response carrying Set-Cookie or Cache-Control: private. Because set() is
still invoked, that payload is handed to the cache handler, which in production may be
backed by a shared out-of-process store — and the handler is trusted to throw it away. If
the framework skipped the write itself, no handler author would have to get that right.

Concretely: is handler-side skipping the intended contract? If so it seems worth
documenting on the cache handler interface. The dev-server exception makes it easy to get
backwards: an author who works this out by observation in dev sees the entry being kept.

2. No way to say "and the previous entry is now wrong"

Both of these are legitimate for a proxy:

• return this, don't store it, keep the previous entry — upstream 500
• return this, don't store it, the previous entry is now wrong — a 403 after the
  caller's permissions changed

expire: 0 gives the first, which is the right default. The second needs
revalidateTag(tag, { expire: 0 }), and that throws inside "use cache" (E181) — so it
can't be reached from the code that just detected it.

The ask

Not a new mechanism, just a name over the existing one:

const res = await fetch(url);
if (!isStorable(res)) {
  unstable_dontCacheThisResult(); // honoured before handler.set() is called
}
return { status: res.status, body: await res.text() };

Contract: the value passes through untouched, no write is attempted at all (so handler
authors need no special case), idempotent, throws outside a "use cache" scope.
Optionally a variant for the second case above.

The expire: 0 spelling works, but it reads as a lifetime tuning knob rather than as
intent, and it leans on a detail I had to read the source to confirm: a partial
cacheLife({ expire: 0 }) is validated in isolation, so it never trips the
revalidate <= expire check even when another call in the same scope sets a longer
revalidate. A named call makes that one documented contract instead.

Thanks again for the detailed answer, useful either way. (On 16.3.2.)