The Vary Header and Its Effect on Caching
A small header with an outsized ability to break — or correctly enable — shared caching behavior.
Core Concept
The Vary header tells caches which request headers were used to determine the specific response returned, so the cache knows when it needs to store separate variants.
Without an accurate Vary header, a shared cache risks serving the wrong version of a response to a client with different needs than the one that originally populated the cache.
How Vary Affects Cache Keys
A cache typically stores responses keyed by URL alone, but Vary extends that key to include specified request headers.
- Vary: Accept-Encoding — separate cached copies per compression format
- Vary: Accept-Language — separate cached copies per language
- Vary: * — effectively prevents caching entirely
Vary: * Is a Blunt Instrument
Using Vary: * tells caches the response can vary on anything, which in practice makes the response effectively uncacheable by shared caches.
What Goes Wrong Without It
Missing or incorrect Vary headers are a common, often subtle, source of caching bugs.
- A compressed response cached and served to a client that can't decompress it
- The wrong language variant served to users who requested another
- Personalized content accidentally cached and shared across users
Balancing Correctness and Cache Efficiency
Broad Vary headers improve correctness but can significantly reduce effective cache hit rates.
The more headers a response varies on, the more distinct cached copies are needed, potentially fragmenting the cache into many rarely-reused entries.
Cache Fragmentation
An overly broad Vary configuration can fragment a cache into so many narrow variants that its effective hit rate drops sharply.
Best Practices for Setting Vary
A well-tuned Vary configuration lists exactly what actually affects the response, no more and no less.
- Include only headers that genuinely change the response content
- Avoid Vary: * unless the response is truly uncacheable
- Normalize header values where possible to reduce unnecessary variant proliferation
Real-World Implementation
Correct Vary header usage is essential for any site relying on shared or CDN-level caching.
- CDNs enforcing correct Vary handling for compressed content
- APIs serving multiple formats relying on accurate Vary configuration
- Caching bugs traced back to missing or overly broad Vary headers
Getting Vary right is a small technical detail with an outsized impact on whether caching actually works correctly across a diverse set of clients.
Common Mistakes to Avoid
A few common mistakes cause Vary-related caching bugs.
- Omitting Vary on a response that legitimately differs based on request headers.
- Using Vary: * broadly, effectively disabling caching for that response.
- Forgetting Vary: Cookie or equivalent on personalized response content.
- Varying on too many headers, fragmenting the cache into rarely reused entries.
- Assuming Vary configuration is correct without testing actual cache behavior.
- Overlooking that some CDNs have limits on how many Vary-based cache variants they'll store.
- Assuming Vary header behavior is identical across all caching layers involved.
- Failing to test cache behavior explicitly after changing a Vary configuration.
- Overlooking that overly broad Vary configuration can make debugging cache behavior harder.
- Assuming Vary header changes take effect immediately for already-cached responses.
- Failing to monitor cache hit rates as an indicator of Vary configuration effectiveness.
- Overlooking that some analytics tools inadvertently add headers that widen Vary-based cache fragmentation.
Best Practices Checklist
These practices help balance caching correctness with cache efficiency.
- Include only headers that genuinely change the response content in Vary.
- Avoid Vary: * unless the response is truly uncacheable by shared caches.
- Normalize input values before they factor into caching decisions to reduce fragmentation.
- Set Vary: Cookie or an equivalent explicitly on personalized response content.
- Test actual cache behavior after setting Vary, not just the header's presence.
- Check CDN-specific limits on Vary-based cache variant storage before relying heavily on it.
- Verify Vary header behavior consistently across every caching layer in the delivery chain.
- Test cache behavior directly after any change to Vary header configuration.
- Keep Vary configuration as narrow as accurately possible to simplify cache debugging.
- Understand that already-cached responses aren't retroactively affected by a Vary header change.
- Monitor cache hit rates as a practical signal of whether Vary configuration is well-tuned.
- Review third-party script-added headers for any unintended impact on Vary-based cache fragmentation.
Frequently Asked Questions
Frequently asked questions about the Vary header.
What does the Vary header actually do?
It tells caches which request headers were used to determine a specific response, so the cache knows when to store separate variants.
What happens without an accurate Vary header?
A shared cache risks serving the wrong version of a response, such as the wrong language or a compressed response to a client that can't decompress it.
Why is Vary: * considered a blunt instrument?
It tells caches the response can vary on anything, which in practice makes the response effectively uncacheable by shared caches.
Can Vary hurt cache efficiency?
Yes — the more headers a response varies on, the more distinct cached copies are needed, which can fragment the cache into rarely-reused entries.
Should Vary be set on personalized content?
Yes — including Vary: Cookie or an equivalent prevents one user's cached, personalized content from being served to a different user.
Do CDNs limit how many Vary-based variants they'll cache?
Some do impose practical limits, which is worth checking if a response varies on many different header combinations.
Is Vary handled consistently by browser, CDN, and origin caches?
Not always identically — behavior can differ slightly between layers, making end-to-end testing valuable.
Should caching be retested after adjusting Vary configuration?
Yes — confirming the actual caching behavior matches what was intended avoids subtle, hard-to-diagnose bugs later.
Does changing Vary retroactively affect already-cached responses?
No — existing cached entries remain as they were; the new Vary behavior only applies to responses cached going forward.
Can cache hit rate reveal Vary configuration problems?
Yes — an unexpectedly low hit rate can indicate an overly broad Vary configuration fragmenting the cache more than necessary.
Can third-party scripts affect Vary-related caching?
Indirectly, if they trigger headers that get factored into Vary, potentially fragmenting the cache more than the site's own configuration intended.
Check Vary Header Configuration
Run an HTTP header analysis to see how a URL's Vary header affects caching.
Launch Tool →