From reading to action
A practical path through this guide.
Select a step to explore what to do and why it matters.
Confirm published source
Check dataset, document identifier and published content before cache investigation.
When a CMS edit does not appear in Next.js, identify which layer is stale before changing cache settings. The CMS response, application data cache, rendered route, CDN, and browser can each retain different state. A blanket cache bypass may conceal the original problem.
Confirm the source changed
Fetch the published CMS document through the same perspective and dataset as the public site. A draft edit does not necessarily change published content. Check the document identifier, slug, and update time without printing access tokens.
Verify that the application is using the intended project and environment. Preview and production deployments can point at different datasets or hosts. A correct revalidation request against the wrong deployment will not update the page you are inspecting.
Trace one content dependency
Map the article detail, blog listing, homepage preview, sitemap, and any generated text routes that depend on the document. Record the cache tags or paths used by each query. Revalidation should cover every relevant view, not only the article body.
Consult the current Next.js caching documentation for your installed version and configuration. Caching behavior depends on the APIs and rendering features used; avoid applying an older recipe without checking its assumptions.
Inspect the invalidation request
Confirm the CMS webhook reaches the expected endpoint, passes authentication, identifies the document type correctly, and requests the relevant invalidation. Log redacted identifiers and outcomes rather than complete webhook payloads.
Return useful failure statuses when authentication or payload validation fails. A handler that always returns success makes a broken publishing path difficult to diagnose. Check provider delivery history and application logs for the same event identifier.
Verify after the fix
- Publish a clearly identifiable test edit.
- Confirm the CMS response includes it.
- Observe the matching invalidation event.
- Request article and listing pages through the public route.
- Inspect sitemap and generated metadata where the edit affects them.
Distinguish immediate expiration from behavior that serves stale content while refreshing, according to the actual API in use. Verify the user-visible result after the relevant refresh cycle. If only one path remains stale, investigate that path's dependencies rather than disabling caching site-wide.
Further reading
See the CMS publishing workflow and technical SEO checklist for a complete editorial verification path.
A few practical answers
Frequently asked questions
What should I check before blaming the Next.js cache?
Confirm the published CMS response in the same dataset and perspective includes the edit. A saved draft is not necessarily the content the public site fetches.
Why might revalidating an article leave its blog card unchanged?
The detail and listing may depend on separate cache tags or paths. Trace every consumer of the document and verify the matching invalidation request.
