Lorixen.
EN

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 Vary value should be sent on all responses for a URL, including 304 Not Modified responses.
  • 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: private or no-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 Vary headers 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

  1. Use your browser's developer tools or curl -I to look at response headers on key pages and API endpoints.
  2. Request the same URL with different Accept-Encoding, Accept-Language or Origin values and compare what comes back.
  3. Look at the CDN's cache status header, which many CDNs add, to see whether responses are hits or misses.
  4. Watch your CDN hit ratio after changes; a sharp drop often means a new Vary value is fragmenting the cache.

When you find a mix-up in production

If visitors are already seeing the wrong version, act in this order:

  1. Purge the affected URLs from the CDN so the bad copies disappear.
  2. Fix the origin's headers, either by adding the missing Vary value or by removing the variation itself.
  3. Set the CDN's cache key to match, if it doesn't follow Vary.
  4. 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.

Sources

WhatsAppBook a call