A product page shows a price that was updated five minutes ago in the CMS, but the public site still renders the old one. The team checks the database: the price is correct. They check the API: it returns the right value. The problem is neither the data nor the query, it's Next.js's caching layer, which Incremental Static Regeneration (ISR) makes both extremely effective and easy to misunderstand.
The concrete problem
ISR lets you generate pages statically at build time, then regenerate them in the background after a configured delay, without rebuilding the whole site. It's the middle ground between pure SSG (fast but frozen) and pure SSR (always fresh but expensive on every request). The trap is that "regenerate in the background" doesn't mean "immediately after the data changes" - it means "on the next request that arrives after the configured delay has elapsed."
How ISR actually works
With the App Router (Next.js 13+), time-based revalidation is configured through revalidate on a segment or inside a fetch call:
// app/products/[slug]/page.tsx
export const revalidate = 300; // 5 minutes
async function getProduct(slug: string) {
const res = await fetch(`https://api.example.com/products/${slug}`, {
next: { revalidate: 300 },
});
if (!res.ok) throw new Error("Failed to fetch product");
return res.json();
}
export default async function ProductPage({ params }: { params: { slug: string } }) {
const product = await getProduct(params.slug);
return <ProductDetails product={product} />;
}
The underlying mechanism is stale-while-revalidate. Here's what actually happens:
- A page is generated and cached with a timestamp.
- For the first 300 seconds, every request gets the cached page instantly, with no call to the API at all.
- After 300 seconds, the next request still gets the cached version (this is the key part people miss), but triggers a background regeneration.
- Once regeneration finishes, the cache is swapped, and subsequent requests get the fresh version.
In other words, between the moment the data actually changes and the moment it's actually visible, you can wait the full revalidate window plus however long it takes for a request to come in and trigger regeneration. For content that rarely changes (an about page, a blog post) that's an excellent tradeoff. For a price or a stock count, it can be an actual functional bug.
Diagnosing the issue
The typical symptom: "it eventually updates, but not right away, and not predictably." To confirm ISR is the culprit rather than a CDN or browser cache issue:
curl -I https://mysite.com/products/running-shoe
The x-nextjs-cache header (on Vercel, x-vercel-cache) reports HIT, STALE, or MISS. A STALE response confirms you're being served an outdated version while regeneration happens in the background.
The fix: on-demand revalidation
For content that must reflect an update immediately after it happens (a price change, a published article, a stock update), the right approach is not shrinking revalidate down to something aggressive like 10 seconds - that just moves the problem around and multiplies calls to the origin. The right approach is on-demand revalidation, triggered by a webhook from the CMS or admin panel:
// app/api/revalidate/route.ts
import { revalidatePath, revalidateTag } from "next/cache";
import { NextRequest, NextResponse } from "next/server";
export async function POST(req: NextRequest) {
const secret = req.nextUrl.searchParams.get("secret");
if (secret !== process.env.REVALIDATE_SECRET) {
return NextResponse.json({ message: "Invalid token" }, { status: 401 });
}
const { slug, tag } = await req.json();
if (tag) {
revalidateTag(tag);
} else if (slug) {
revalidatePath(`/products/${slug}`);
}
return NextResponse.json({ revalidated: true, now: Date.now() });
}
On the fetch side, attach a tag instead of relying only on a time delay:
const res = await fetch(`https://api.example.com/products/${slug}`, {
next: { tags: [`product-${slug}`] },
});
The CMS (or the admin endpoint that updates the price) then calls /api/revalidate right after the database write, with the relevant tag. The cache gets invalidated at exactly the right moment, with no polling and no performance sacrifice the rest of the time. That's the difference between time-based revalidation (approximate, fine for latency-tolerant content) and event-based revalidation (precise, needed for sensitive content).
A common trap: data cache vs client-side router cache
Even after a successful server-side revalidation, a user navigating client-side can still see the old page, because Next.js's Router Cache (client-side, in the browser) keeps its own segments in memory during navigation, independent of the server-side data cache. A full navigation (page reload, or a return visit after enough time) eventually resyncs, but this is why a successful revalidatePath on the server doesn't always show up "immediately" in a tab the user already had open while navigating between pages on the same site without a reload.
The trap of never-prebuilt pages: dynamicParams and the first visitor
ISR isn't only about revalidating pages that were already built: you also need to decide what happens for a path that wasn't included in generateStaticParams at build time, typically a product added after the last deployment.
// app/products/[slug]/page.tsx
export async function generateStaticParams() {
const products = await getTopProducts(500); // only the 500 most-viewed at build time
return products.map((p) => ({ slug: p.slug }));
}
export const dynamicParams = true; // default behavior: allows slugs that weren't pre-generated
With dynamicParams set to true (the default), the first visitor hitting a slug that wasn't pre-generated triggers an on-demand server render, which then gets cached like any other ISR page for subsequent visitors. That first visitor pays the latency cost of that initial render, but gets no 404. This is the desirable behavior for a catalog that keeps growing.
The trap shows up when dynamicParams is set to false to "lock down" a fixed catalog: any page not included in generateStaticParams then returns a 404, even if the product genuinely exists in the database. That's sometimes a legitimate choice (content intentionally limited to a known set), but it's a frequent cause of "why does this product I just published return a 404" when that choice was made without the whole team knowing about it.
Draft content: draft mode and intentionally bypassing the cache
A related but different case: an editor wants to preview an unpublished article, or a product page with a price that isn't effective yet, without waiting for a revalidation and without affecting what other visitors see. Next.js's Draft Mode exists exactly for this, bypassing the ISR cache for the editor's session only.
// app/api/draft/route.ts
import { draftMode } from "next/headers";
import { redirect } from "next/navigation";
export async function GET(request: Request) {
const { searchParams } = new URL(request.url);
const secret = searchParams.get("secret");
const slug = searchParams.get("slug");
if (secret !== process.env.DRAFT_SECRET) {
return new Response("Invalid token", { status: 401 });
}
(await draftMode()).enable();
redirect(`/products/${slug}`);
}
// app/products/[slug]/page.tsx
import { draftMode } from "next/headers";
async function getProduct(slug: string) {
const isDraft = (await draftMode()).isEnabled;
const res = await fetch(`https://api.example.com/products/${slug}?preview=${isDraft}`, {
cache: isDraft ? "no-store" : "default",
next: isDraft ? undefined : { tags: [`product-${slug}`] },
});
return res.json();
}
The draft mode cookie only affects the browser that enabled it: every other visitor keeps getting the normal cached version. This is a distinct tool from on-demand revalidation, but the two complement each other in a real editorial pipeline: draft mode for previewing before publication, revalidateTag for the actual update once it's published.
When the fix isn't enough
For data that must be guaranteed accurate to the millisecond (an account balance, seat availability in a booking flow), ISR simply isn't the right tool, even with on-demand revalidation: there's always a cache window, however short. In that case, the right approach is explicit dynamic rendering (export const dynamic = "force-dynamic", or a fetch call with cache: "no-store") on that specific segment, accepting the server compute cost on every request, while keeping ISR for the rest of the site that doesn't carry that constraint.
Takeaway
ISR never guarantees immediate freshness by default: it guarantees freshness bounded by your revalidation delay, plus an additional lag tied to traffic. For critical content, replace the time-based delay with event-driven invalidation via revalidateTag or revalidatePath fired at the exact moment the data is written, and reserve fully dynamic rendering for data that can't tolerate any cache window at all.
