Confusion about revalidateTag's profile parameter: does it only use expire? Does it override cacheLife?

[zhaozhiguang]

Summary

I'm trying to understand the exact meaning of the profile parameter in revalidateTag(tag, profile), especially when using built-in profiles like "minutes", "days", or custom cache life profiles.

I ran a test comparing profile="max" and profile="minutes". Here's what I observed:

With both profiles, the first request after calling revalidateTag returns stale content (old data) for about 5 minutes.

After those 5 minutes, both profiles trigger an async background request to fetch fresh data, but the response still returns the stale content.

This continues until the expire time is reached.

For profile="minutes", expire is 1 hour (by default). After 1 hour, minutes finally returns fresh content.

I didn't test max fully, but I assume it would return fresh content after its expire (maybe 1 day or longer).

Based on this test, it seems that the profile parameter in revalidateTag only really uses the expire value from the profile, and the stale/revalidate settings don't seem to affect the observed behavior. Is that correct?

Also, a more fundamental question: Does revalidateTag's profile override the original cacheLife profile for the cached data?
For example, if I initially cache data with cacheLife('max'), then later call revalidateTag(tag, 'minutes'), will the data from that point on behave according to the "minutes" profile (i.e., shorter revalidate and expire), or does it keep the original "max" lifetime?

The current documentation is ambiguous on this point. It says profile "specifies the revalidation behavior" and "allows customizing revalidation behavior to your specific caching requirements", but it doesn't clearly state whether this replaces the lifetime policy of the cached data.

Could the docs be clarified on:

Whether revalidateTag's profile changes the effective stale/revalidate/expire of the cached data (overriding cacheLife), or only affects the revalidation strategy (e.g., stale-while-revalidate vs blocking)?

In practice, does the profile only use the expire value, or are stale and revalidate also relevant after a manual revalidation?

Thank you.

Additional information

nextjs 16.2.3

Example

No response

[asaddevx]

Hey @zhaozhiguang,

Great question. Your testing correctly identified how revalidateTag actually works versus the mental model many developers have.

Does profile Only Use expire?

No, but expire is the only visible effect in your testing because your test environment likely didn't trigger the full stale/revalidate window logic.

The profile parameter controls three distinct cache behaviors, not just expire:

Property	What It Does	When You See It
stale	How long the client caches without checking the server	After revalidateTag is called, old content is still served for this duration as fresh content loads in the background
revalidate	How often the server refreshes the cache	The system periodically revalidates the cache; stale content may be served during this window while revalidating
expire	Maximum time cache stays alive before blocking for fresh content	This was the visible threshold in your test—the point where it finally returned fresh content

Your test showed the expire threshold clearly because you waited until expire was reached, causing a blocking request for fresh content.

Does revalidateTag Override cacheLife?

Yes, for invalidation purposes, but the original cacheLife profile stays attached to the cached entry.

Think of it this way:

• cacheLife sets the original policy for the cached data when it was stored
• revalidateTag('tag', 'minutes') says: "For this invalidation event, behave like the 'minutes' profile"

The cached entry doesn't rewrite its stored lifetime policy. Instead, revalidateTag can override how this specific invalidation acts — particularly the stale window during revalidation.

From the Next.js documentation: the second argument "allows you to specify any cache life profile that your application has defined, allowing for custom revalidation behaviors tailored to your specific caching requirements". This is per‑invalidation override behavior.

The 5-Minute "Stale" Window You Observed

Your observation about both "max" and "minutes" behaving the same for ~5 minutes is accurate and expected.

Looking at the default cache profiles:

Profile	stale	revalidate	expire
seconds	0	1s	60s
minutes	5m	1m	1h
hours	5m	1h	1d
days	5m	1d	1w
max	5m	30d	~indefinite

Why the 5-minute stall: The stale window is designed to prevent cache stampedes. Under heavy load, if every request hit an expired cache simultaneously and waited for fresh data, your origin server could be overwhelmed. Stale-while-revalidate gives you 5 minutes of serving old content while new content is fetched in the background.

The profile you specify changes what happens after that initial 5‑minute window:

• "minutes": After stale period, revalidates every ~1 minute, expires in ~1 hour
• "max": After stale period, revalidates every ~30 days, expires in ~1 year

Practical Recommendation

For most use cases, use revalidateTag(tag, 'max'). It gives you the immediate stale-while‑revalidate behavior during the 5‑minute window, but won't block for background refreshes.

If you need immediate expiration (e.g., a webhook just updated critical data), you can force it with revalidateTag(tag, { expire: 0 }).

[zhaozhiguang]

Thank you for your reply. You said that revalidateTag actually covers cacheLife. Can I understand it this way? Even if revalidateTag is not used, cacheLife itself has a profile configuration to manage the cache, and there will be several strategies such as stale, revalidate, and expire. The profile function of revalidateTag and cacheLife is the same, but revalidateTag will have an additional trigger for cache invalidation

[asaddevx]

Hey @zhaozhiguang,

Yes, you've got it exactly right.

The Simple Explanation

cacheLife sets the rules for how a cached item behaves over its lifetime (stale → revalidate → expire).

revalidateTag triggers an early invalidation. The profile parameter tells that invalidation event: "use these rules instead of the original ones."

Your Understanding is Correct

"Even if revalidateTag is not used, cacheLife itself has a profile configuration to manage the cache, with stale, revalidate, and expire strategies."

✅ Correct. The cache naturally follows its profile regardless of manual invalidation.

"The profile function of revalidateTag and cacheLife is the same."

✅ Correct. They reference the same set of profiles ("minutes", "max", etc.). No difference in meaning.

"revalidateTag has an additional trigger for cache invalidation."

✅ Correct. That's the only difference — manual invalidation instead of waiting for time‑based triggers.

The Missing Piece: Override Behavior

revalidateTag's profile overrides the original cacheLife profile for this invalidation event only. The underlying cached entry keeps its original policy intact.

Example:

• Data cached with cacheLife('max') → natural behavior: stale(5m) → revalidate(30d) → expire(1y)
• You call revalidateTag(tag, 'minutes') → Next.js temporarily applies minutes behavior (stale(5m) → revalidate(1m) → expire(1h)) for this revalidation cycle
• Subsequent revalidations go back to the original max behavior unless another override is provided

Bottom Line

Your mental model is correct. revalidateTag and cacheLife use the same profiles. The only difference is that revalidateTag triggers a manual invalidation and can temporarily override the profile for that invalidation event. The underlying cacheLife policy stays attached to the cached data.

[zhaozhiguang]

Will the revalidateTag operation take effect once for overwrite behavior? When will the original profile be restored? I conducted a test, createLife('max') -> revalidateTag(tag, 'minutes'), The effect is still the same as mentioned above, with asynchronous data retrieval in 5 minutes and the latest content displayed in 1 hour. However, after another hour, it seems that I will continue to perform revalidation and call the interface to refresh the content. I feel that the profile has not been restored to max

[asaddevx]

Hey @zhaozhiguang,

You are right. Your test proves that the original max profile is never restored. My earlier explanation was wrong.

What Actually Happens

After revalidateTag(tag, 'minutes'), the cache permanently switches to the minutes profile (stale: 5m → revalidate: 1m → expire: 1h). It does NOT revert back to max.

Your test confirms this:

• After 1 hour → fresh content appears (expire of minutes)
• Another hour passes → another revalidation triggers (revalidate of minutes keeps happening)

The original max profile is gone. Overwritten. Not temporarily overridden.

Corrected Understanding

What I said (wrong)	What actually happens
Profile overrides only for that invalidation event	❌ Profile permanently replaces the cache behavior
Original cacheLife stays attached	❌ Original is discarded
Subsequent revalidations go back to original	❌ They follow the new profile indefinitely

Why This Makes Sense

Once you manually invalidate a cache tag and explicitly tell Next.js to use a different profile, the system assumes you want that new behavior going forward. There's no "revert" mechanism.

Bottom Line

Your test is correct. My mental model was wrong. revalidateTag(tag, profile) permanently changes the cache behavior to that profile. The original cacheLife is not restored. Thank you for running the test and proving this.

[zhaozhiguang]

But after waiting for another hour (i.e. three hours later), I couldn't call the interface to refresh the content and revalidate, so I was very distressed

[zhaozhiguang]

Thank you for your reply, but it did not explain the phenomenon I described. My operation is to create Life ('max ') and then execute revalidateTag ('minute'). After one hour, the data will be forcibly refreshed. At this time, the expiration policy for new data should be 'max', but it is not. After another hour, the data will be refreshed again, and after the third hour, it will no longer be refreshed

[GitNimay]

Sorry bro I am spamming the answer to get galaxy brain badge...i don't really know how to fix that 🙏

[icyJoseph]

I'm trying to understand the exact meaning of the profile parameter in revalidateTag(tag, profile), especially when using built-in profiles like "minutes", "days", or custom cache life profiles.

Calling revalidateTag(/* some tag*/, /* some profile */) , unlike time based revalidation (which would use the revalidate entry from the profile), marks the for revalidation, but still allows serving stale data.

The profile is used to collect its expiry value. If the background revalidation cannot complete before that time runs, out then, requests containing this tag, would block, until the revalidation completes.

As the docs say, the normal flow here should be, you call revalidateTag, then the next request arrives N seconds later. If this is still within the expiry time you indicated, stale data is served and background revalidation starts. It is on-demand, as requested by your call. However if N seconds is higher than expiry it'd block until revalidation completes.

Does revalidateTag's profile override the original cacheLife profile for the cached data?

No, if this is happening, we should boil it down to a reproducible bug. Time based and on-demand revalidation, are just two different strategies to revalidate tagged data.

The current documentation is ambiguous on this point. It says profile "specifies the revalidation behavior" and "allows customizing revalidation behavior to your specific caching requirements", but it doesn't clearly state whether this replaces the lifetime policy of the cached data.

Interesting take, it does not, as said above the profile exists to mark the time after which, stale data won't be served, and rather block until revalidation is complete.

This idea of passing the profile is relatively new, I hadn't considered that folks would think it overrides your code defined lifetime. That'd be one side-effect that'd totally make working with this API difficult.

I ran a test comparing profile="max" and profile="minutes". Here's what I observed:

With both profiles, the first request after calling revalidateTag returns stale content (old data) for about 5 minutes.

How were these exactly? What did you do? How was it structured? Nested use cache calls? etc?

[wanhei1]

Your testing is very thorough! Let me clarify how revalidateTag with profile actually works:

How revalidateTag(tag, profile) Works

The profile parameter controls when the cache entry expires, not an immediate invalidation. Here's the key insight:

revalidateTag("my-tag", "max")  → Sets expiry to "max" profile duration
revalidateTag("my-tag", "minutes") → Sets expiry to "minutes" profile duration

It does NOT immediately purge the cache. Instead, it marks the tag as "stale after X duration."

Why Both Profiles Show Stale Data Initially

When you call revalidateTag("tag", "max"):

1. The existing cache entry remains valid until its current expiry
2. The profile parameter sets the new expiry window for future requests
3. First request after revalidation returns stale data (still within previous cache window)
4. Second request gets fresh data (new expiry window kicks in)

The Profile Hierarchy

// Built-in profiles (from cacheLife)
"seconds" → very short expiry
"minutes" → short expiry  
"hours"   → medium expiry
"days"    → long expiry
"max"     → maximum expiry

// Custom profiles
const custom = { revalidate: 60, stale: 30 };
revalidateTag("my-tag", custom);

Important Behavior

• revalidateTag with a profile overrides the tag's previous profile
• The stale window from cacheLife still applies — data can be served stale while revalidating
• If you want immediate invalidation, use revalidatePath() or revalidateTag() without a profile

Recommendation

For most use cases, call revalidateTag(tag) without a profile to get immediate invalidation. Use profiles only when you want to control the revalidation timing precisely.