Vary header

The Vary header tells caches which request headers change the response for the same URL. Every distinct combination of the listed header values gets its own cache entry. Used well, Vary keeps caches correct; used carelessly, it quietly multiplies your cache entries until nothing hits.

The canonical example

Vary: Accept-Encoding

A Brotli-capable browser and an old client without compression support must not receive each other's bytes — so the cache stores one entry per encoding. This one is near-universal and harmless: there are only a handful of encodings in the wild (check which your site serves with the compression test).

How Vary shatters hit ratios

The cache entry count is the product of the value spaces of every listed header:

• Vary: User-Agent — thousands of distinct UA strings mean your one URL becomes thousands of cache keys, almost all of which will never be requested twice. Hit ratio ≈ 0.
• Vary: Cookie — effectively one cache entry per visitor. For personalized pages that's honest (or use Cache-Control: private), but a session cookie on otherwise-static pages destroys shared caching entirely.
• Vary: * — "never reuse this for anyone". A cache-buster in header form.

What CDNs actually do

Because unbounded Vary is so destructive, most CDNs constrain it: many only honor Vary: Accept-Encoding by default and offer explicit cache-key rules for anything else (device type, language, A/B bucket). That's usually the better tool — you enumerate the variants you actually serve (say, mobile|desktop) instead of keying on a free-text header. If your hit ratio looks inexplicably low, inspect the response's Vary header early — and remember each variant also needs its own warming, since a warm desktop variant does nothing for the first mobile visitor.