A cached response can be fresh and still be wrong for your request. The Vary header tells caches which request differences matter when choosing a response to reuse.
Key Takeaways
- Vary selects matching representations; Cache-Control governs storage and freshness.
- Include request headers that actually influence the response.
- Verify CDN behavior instead of assuming identical support.
What Is the Vary Header?
The Vary header is an HTTP response header naming request headers that influenced representation selection. You commonly use it for content negotiation, where one URL serves different formats or languages.
Within HTTP caching, the Cache-Control header governs cacheability and freshness. Vary determines which stored variant matches your request. Setting Vary alone neither grants permission to cache nor extends freshness. For example, max-age=300 gives a cacheable response a five-minute freshness lifetime, independent of its selected variant.
{{cool-component}}
How Caches Use the Vary Header to Serve Correct Content
Under RFC 9111 Section 4.1, a conforming cache must match every nominated request header against the original request before reusing that response without revalidation. Matching allows normalization that preserves the header's meaning. After normalization, an absent nominated header matches only another request where that header is absent.
Suppose /app.js returns gzip content for Accept-Encoding: gzip, with Vary: Accept-Encoding. A later request for that same URL with Accept-Encoding: identity cannot reuse the gzip variant without revalidation. With no matching entry, the cache normally forwards your request upstream.
Vary: * always fails to match, so it prevents unvalidated reuse. It does not mean cache everything.
The Most Common Vary Header Use Cases
Choose fields based on how your server selects responses, including headers as well as bodies.
List multiple fields together when selection depends on both, such as Vary: Accept-Encoding, Accept-Language.
How the Vary Header Affects CDN Cache Hit Rates
Each distinct combination can split traffic across additional variants, reducing reuse and increasing origin requests. Rare variants may expire or be evicted before another matching request arrives. For better CDN performance, retain necessary distinctions while removing inputs that never change the representation.
Broad User-Agent or Cookie variation can create many scarcely reused entries. Vary is not an authorization boundary: avoid CDN security risks by keeping user-specific responses out of shared caches. Use Cache-Control: private to prohibit shared storage, or no-store when nothing should be stored. Remove CDN overrides that force caching.
{{cool-component}}
How to Configure the Vary Header Correctly Across CDN Providers
I'd check each provider's cache-key policy before deployment. CloudFront keys on headers included in its cache policy, not merely forwarded headers. Cloudflare offers configurable Vary support; verify enabled fields and effective keys.
- Emit consistent Vary fields across variants, including default and 304 responses.
- Align header forwarding, normalization, and cache keys with origin selection.
- Test repeated requests for each variant through every provider.
- Purge obsolete entries after changing cache keys or variation rules.
Conclusion
Use Vary to preserve correct response selection, keep variation limited to meaningful inputs, and verify both cache hits and returned content across your delivery path.
FAQs
Does the Vary Header Apply to Browser Caches Too?
Yes. Browser HTTP caches honor Vary when deciding whether a stored response matches your request. Their storage strategy can differ from a CDN's: some implementations keep one variant and replace it when preferences change. Do not assume every browser stores multiple variants simultaneously.
How Does Vary: Origin Interact With CORS Caching?
Use Vary: Origin when Access-Control-Allow-Origin changes according to the requesting origin. This keeps cached CORS response headers associated with the right request origin. Your server must still decide which origins have permission. Browser preflight caching is separate and uses Access-Control-Max-Age; Vary does not configure it automatically.
What If Two CDN Providers Handle Vary Differently?
You can receive inconsistent content or different cache hit rates during traffic shifts. Configure each provider to distinguish the same request headers, then test equivalent requests against both. Where safe separation is unavailable, bypass caching for that response rather than risk serving an incorrect variant.
Why Does Vary: User-Agent Devastate CDN Cache Efficiency?
User-Agent strings contain many combinations of browser versions and device details. Using the entire value creates separate variants even when your server returns identical content. Each variant receives fewer repeat requests. Prefer responsive content or a small, explicitly defined device classification when representations genuinely differ.
How Do You Debug Vary-Related Cache Misses?
Repeat the same URL while changing one nominated request header at a time. Compare response bodies, Vary, Age, and provider cache-status headers. Then inspect the effective cache key and origin logs. Separate expected first requests for new variants from repeated misses caused by inconsistent headers or cache bypass rules.
