The Vary header: caching different versions without mix-ups
Short answer: The Vary response header tells caches, including browsers and CDNs, which request headers changed the response, so they store separate copies instead of serving one visitor's version to everyone. If your server sends different content by compression, language, cookie or device, it must say so in Vary, or a CDN may hand the mobile page to desktop users or French text to English visitors. Keep Vary to the headers that really matter, because each one multiplies the copies a cache must store.
The mix-ups Vary prevents
Picture a site that serves different HTML depending on something in the request:
- Compressed or uncompressed content, depending on
Accept-Encoding. - English or Welsh pages, depending on
Accept-Language. - A mobile or desktop layout, depending on
User-Agent. - A logged-in or logged-out version, depending on a cookie.
A cache in the middle, such as a CDN, normally keys stored responses by URL. Without more information, it stores whichever version it saw first and serves it to the next visitor, whatever their browser, language or login. The result is the kind of bug that's maddening to debug: it only appears sometimes, for some people, and clearing the cache "fixes" it until it happens again.
What Vary does
MDN's reference explains that the Vary header lists the request headers that influenced the response, so responses are cached separately based on those headers; most often it's used to build a cache key when content negotiation is in use. The HTTP caching standard, RFC 9111, describes how a cache uses it: when a stored response carries Vary, the cache may only reuse it for a new request whose nominated request headers match those of the original request.
So with Vary: Accept-Language, a cache keeps one copy for requests sent with Accept-Language: en-GB and another for cy, and serves each to matching visitors.
MDN also notes two important details:
- The same
Varyvalue should be sent on all responses for a URL, including304 Not Modifiedresponses. Vary: *means factors other than request headers affected the response, which effectively makes it uncacheable.
Common cases and what to send
| What changes the response | Header to list | Notes |
|---|---|---|
| Compression (gzip, Brotli) | Accept-Encoding |
Most servers add this automatically; check |
| Language negotiation | Accept-Language |
Many sites use separate URLs per language instead |
| Device-specific HTML | User-Agent |
Fragments caches heavily; prefer responsive design |
| Logged-in content | Cookie |
Usually better marked private or not cached |
| CORS responses differing by origin | Origin |
Needed when Access-Control-Allow-Origin echoes the request origin |
The last one catches many APIs. If your server sets Access-Control-Allow-Origin to whichever origin made the request, a cache without Vary: Origin can serve one site's CORS header to another, and browsers then block the request.
Why fewer is better
Each header in Vary splits the cache. Accept-Encoding has a handful of common values, which is fine. User-Agent has thousands of variants, so a CDN may store a separate copy for almost every browser version, and hit rates collapse. Cookie can be even worse.
That's why the usual advice is to avoid varying on high-variety headers where possible:
- Devices: use responsive design so one HTML response works everywhere. Google's mobile-first indexing guide describes responsive design as the easiest pattern to implement and maintain, compared with dynamic serving, which relies on user-agent sniffing and
Vary: User-Agent. - Languages: give each language its own URL, such as
/en/and/cy/, and let visitors switch, rather than negotiating on every request. - Logged-in pages: mark them
Cache-Control: privateorno-store, so shared caches don't store them at all.
CDNs have their own rules
CDNs don't all handle Vary the same way. Some honour only certain headers, normalise values like Accept-Encoding, or ignore Vary and use their own cache-key settings. Check your CDN's documentation for:
- Which
Varyheaders it respects. - Whether it normalises encodings or languages.
- How to add headers or cookies to the cache key directly.
If the CDN uses its own cache-key settings, configure those to match what your origin varies on.
How to check your site
- Use your browser's developer tools or
curl -Ito look at response headers on key pages and API endpoints. - Request the same URL with different
Accept-Encoding,Accept-LanguageorOriginvalues and compare what comes back. - Look at the CDN's cache status header, which many CDNs add, to see whether responses are hits or misses.
- Watch your CDN hit ratio after changes; a sharp drop often means a new
Varyvalue is fragmenting the cache.
When you find a mix-up in production
If visitors are already seeing the wrong version, act in this order:
- Purge the affected URLs from the CDN so the bad copies disappear.
- Fix the origin's headers, either by adding the missing
Varyvalue or by removing the variation itself. - Set the CDN's cache key to match, if it doesn't follow
Vary. - Re-test with the different request headers before declaring it fixed.
Purging alone only hides the problem until the next unlucky request fills the cache again.
A worked example
Consider a hypothetical Cardiff theatre whose site served English and Welsh pages at the same URLs, choosing by the browser's language. Visitors sometimes got the wrong language, and the box office fielded confused calls. The CDN was caching by URL alone. The developer moved each language to its own URL path with a language switcher and hreflang tags, removed language negotiation from the main pages and kept Vary: Accept-Encoding for compression. The wrong-language reports stopped and the CDN's hit ratio improved.
FAQ
Does Vary affect SEO?
Indirectly. Google's documentation mentions Vary: User-Agent for dynamic serving setups. Separate URLs or responsive design avoid needing it.
Should I add Vary: Cookie everywhere?
No. It can make shared caching almost useless. Mark personalised pages as private instead.
Do browsers use Vary too?
Yes. The browser cache follows the same rule when reusing stored responses.
If your CDN sometimes serves the wrong version of a page, ask us to check your caching headers.