Cloudflare has made Vary accessible to ordinary users at last, and the company is quick to spread the word. The feature places control over HTTP’s most confusing header directly in the hands of customers. Rather than allowing Vary to break your cache, you can now instruct Cloudflare which variations truly matter.
The announcement comes with a warning. Vary is “the ugliest part of HTTP that we haven’t yet improved,” as one post put it, and it carries “pretty abysmal interoperability” across intermediaries. That is usually where sensible engineers back away slowly with their hands raised. But Cloudflare is not backing away. The company has built a system that lets customers decide how much variation is meaningful for the cache, rather than being stuck with whatever the origin declares.
What Vary Actually Does
The Vary header is an HTTP response header that instructs intermediary caches, such as Cloudflare, which request fields may influence the response issued by the origin server. A server could deliver various image formats to different browsers, or serve distinct languages from the same URL. If a cache overlooks Vary, it risks serving the wrong bytes to a request. Yet if it regards every raw header value as separate, a small number of related requests can expand into thousands of barely reusable cache entries.
A header is easy to explain yet difficult to handle. The source identifies the request headers that might influence a response, while you choose how Cloudflare deals with each one. You can standardize well-known negotiation headers, send exact values through when those slight differences count, or avoid the cache when the variation proves too unpredictable.
The Central Problem
The trouble starts with the header’s limits. It points out which request fields could influence a response, yet it fails to say which actual changes truly count. That gap is exactly what makes things difficult.
Suppose a single URL can produce two distinct valid versions of a webpage. When a browser asks for it,
GET /catalog HTTP/1.1
Host: example.com
Accept: text/html
HTML is returned by the origin, and Accept is identified as a field whose presence may influence the response.
The response begins with an HTTP status line announcing a successful request: HTTP/1.1 200 OK. Below it comes a content header specifying the document type, followed by a cache directive that sets a public maximum age of 3600 seconds. The final header, Vary: Accept, signals that the server’s response can vary depending on what the client accepts.
When an API client sends a request to the same URL, it can specify a different preference.
GET /catalog HTTP/1.1
Host: example.com
Accept: application/json
This time, the correct reply is JSON. The Vary: Accept header indicates that the cache should not rely solely on the URL to select a response; it must also take into account the request’s Accept value.
Without Vary, the first response to enter the cache can be served to both clients, regardless of which one it is. If HTML arrives before JSON, then the API client gets markup and its JSON parser fails. If JSON arrives first instead, a browser expecting a web page gets an API response. Vary stops the cache from serving the wrong response to the requesting client. Still, it raises a more difficult question: when two requests carry different header values, do they really need separate responses?
When Correct Caching Becomes Useless
A situation grows more complicated when a response changes across several fields at once. Consider an origin that offers content in just three languages — English, French, and German — and imagine what happens when a client sends a request that asks for information on more than one of those fields at the same time.
Accept-Language: en-US, fr;q=0.8
While another client might request:
Accept-Language: fr;q=0.8, en-GB
The two requests ask for the same language, yet the server treats them as distinct, storing each as its own version despite matching content. This happens because each request carries its own order and language tag, and the server cannot tell these apart on its own. So two identical responses can end up stored as separate variants in the cache.
The core issue with Vary is that apps frequently create a limited number of output formats from a vast array of potential input requests. The source system recognizes that many user preferences for language boil down to just three supported options, whereas a cache generally lacks that context.
A cache can end up perfectly accurate yet almost perpetually cold. Similar answers can be distributed across entries that see too little traffic to stay hot and in cache. These can take up space, push each other out, lower hit rates, and force more calls back to origin servers. While eviction removes cold entries, it offers no way to combine them simply because their responses match.
A study based on over 120 million answers from close to 50,000 well-known websites discovered nearly 3,000 of them differing across four or more categories. Others changed on just 10, 23, or as many as 47 categories. The firm aims to ensure users possess the means to apply Vary appropriately, without building an excess of unnecessary storage.
High-Cardinality Variation Is Deliberate
Certain changes are intentional. Content delivery networks and reverse proxies can add values, including a geographic region, to organize content systematically. This approach succeeds when the potential values are limited and all components share the same understanding of what they mean. Otherwise, the cache breaks apart into variants that might never be used again.
How Cache Rules Control Vary
Before today, Cloudflare customers had several approaches for dealing with content that needed negotiated handling, much like what Vary does. They could choose to skip the cache entirely and let their origin server manage the negotiation directly. They could also build a custom cache key or apply another rule that mimics the origin’s negotiation logic. A Worker was another option, or they could take advantage of features like Vary for images. All of these methods still work, but each comes with trade-offs: some give up caching altogether, some require duplicating the application’s logic, some demand writing extra code, and others cover only a more limited set of cases.
This revised Cache Rules method keeps enough variety to deliver the correct answer while stopping minor differences between requests from ruining cache performance. The origin continues to identify which request headers can influence a response, yet it is you who determines how much variation truly matters for the cache.
The Numbers Behind the Problem
- More than 120 million responses analyzed from nearly 50,000 popular sites
- Almost 3,000 sites varying on four or more fields
- Some varied on 10, 23, or even 47 fields
- Real headers can have far greater cardinality: User-Agent values are numerous, cookies can be unique to individual visitors, and preference headers can differ in ordering, formatting (spaces and tabs matter!), and quality values
Comparison of Vary Handling Approaches
| Approach | What It Does | Tradeoff |
|---|---|---|
| Bypass cache | Let the origin handle negotiation | Gives up caching entirely |
| Custom cache key | Reproduce origin logic in a rule | Duplicates application logic |
| Use a Worker | Handle variation programmatically | Requires additional code |
| New Cache Rules | Decide which variation matters | Preserves cache efficiency |
What Customers Can Do Now
Every plan now supports the feature, which lets you state what can change at the source and then set your own limit on how much difference matters for the stored copy. It goes beyond what was possible before.
The firm has created a method that enables users to decide which versions matter and which ones are simply background static. Cloudflare is now placing that remedy before its audience while also offering an explanation for the issue itself.
The feature has gone live. Sites that use Vary should put it through its paces, since the other option is a cache that functions properly yet never hands over a single item.
The analysis draws on 120+ million responses gathered from nearly 50,000 popular sites, with over 3,000 of those sites varying on four or more fields. Some sites differed on just 10, while others varied across 23, or even up to 47 fields. The data is available on every plan.
A solution to what was once the ugliest part of HTTP now exists, and whether you put it into use depends on your particular site.
Source material: “We just shipped support for the ugliest part of HTTP: Vary,” cloudflare.com.
Get the Notebook.
The day's best stories and every fresh verdict, in plain English, in your inbox by seven. One email a day, no more.