revalidateTag with expire: 0 not triggering immediate UI update when called from API route

[rRakarare]

Summary

Describe the bug

When using revalidateTag() with { expire: 0 } from an API route, the cache invalidation works but the UI doesn't update immediately. A manual page refresh is required to see the new cached value. This differs from server actions, which trigger immediate UI updates.

Reproduction

Repository:

Cached server function:

"use server";
import { cacheTag } from "next/cache";

export async function getCachedValue() {
  "use cache";
  cacheTag("random");
  return Math.random();
}

Server action (immediate UI update ✅):

"use server";
import { revalidateTag } from "next/cache";

export async function invalidateCache() {
  revalidateTag("random", { expire: 0 });
}

API route (requires page refresh ❌):

import { revalidateTag } from "next/cache";

export async function GET() {
  revalidateTag("random", { expire: 0 });
  return Response.json({ revalidated: true });
}

Expected behavior

According to the documentation, { expire: 0 } should lead to immediate new values. When calling the API route, the page should automatically display the fresh cached value without requiring a manual refresh, matching the server action behavior.

Actual behavior

• Server action: Page immediately shows new value after invalidation
• API route: Cache is invalidated successfully, but page continues showing old value until manually refreshed

Question

How can I achieve the same immediate UI update behavior with API route calls as with server actions?

Additional information

### Version
- Next.js: 16.0.7
- React: 19.2.0
- React DOM: 19.2.0

Example

https://github.com/rRakarare/Next-js-cache-purge-via-route

[icyJoseph]

When calling the API route, the page should automatically display the fresh cached value without requiring a manual refresh, matching the server action behavior.

That's a misunderstanding there. Server Functions/Actions communicate with the client router to achieve this kind of thing, where they can do UI updates, or redirect based on some special headers returned from the Server Function.

An API Route or Router Handler, are a primitive escape hatch, to put it in another way, as far as they are concerned, the rest of your app doesn't exist. I think you'd need to do router.refresh after your fetch call to the API or Route Handler succeeds. They are nothing but a REST API call.

I'll review the docs to make sure this is properly communicated, I thought it was though. How did you arrive to this conclusion?

[rRakarare]

Thanks for the response! I got my initial understanding from the Next.js documentation here:
https://nextjs.org/docs/app/api-reference/functions/revalidateTag
Specifically, this note at the bottom of the page:

Good to know: For webhooks or third-party services that need immediate expiration, you can pass { expire: 0 } as the second argument: revalidateTag(tag, { expire: 0 }). This pattern is necessary when external systems call your Route Handlers and require data to expire immediately. For all other cases, it's recommended to use in Server Actions for immediate updates instead.

I think I misread it a bit, i interpreted revalidateTag(tag, { expire: 0 }) in Route Handlers as the alternative that would work like updateTag, but as you explained, it only invalidates the cache without triggering UI updates and that makes totally sense now to me. So if i want to see updates in the ui i have to implement some further communication between server and client. Tanks

[icyJoseph]

I see, well feedback is feedback, need to refine the wording.

So say

• you are in another application, App A
• your Next.js app is App B,

And now you want to call an endpoint in App B, from App A, in such a way that, users browsing a given route in App B, would suddenly start to see updated data? There'd need to be some sort of polling, or websocket mechanism no? to inform the client side app that something changed upstream.

[rRakarare]

Yes exactly, thanks again for the enlightenment :)