What is the documentation issue?

The current documentation explains how revalidation works, including the tag system and cache invalidation, but it does not clearly highlight that revalidation is instance-local by default.

In multi-instance or serverless environments (such as Vercel), calling revalidateTag() or revalidatePath() only invalidates the cache on the instance handling the request. Other instances may continue serving stale content until they receive the invalidation signal.

This behavior is mentioned in the "Multi-Instance Considerations" section, but it is not clearly surfaced in higher-level caching or revalidation guides. As a result, developers may assume that revalidation is globally consistent by default, which can lead to confusing production behavior.

It would be helpful to add a more prominent note or warning in the main caching/revalidation documentation to clarify this limitation.

Is there any context that might help us understand?

Most developers deploy Next.js apps on serverless or multi-instance platforms where this limitation is relevant by default.

Without understanding this behavior, developers may expect revalidation to propagate globally, leading to inconsistent UI or stale data across requests.

Highlighting this earlier in the documentation (for example in caching or revalidation guides) would improve clarity and prevent confusion.

Does the docs page already exist? Please link to it.

https://nextjs.org/docs/app/guides/how-revalidation-works