HTTP Cache-Control and ETag: Eight Silent Defaults
Caching on a static site never throws an error. It just makes you re-upload a file you already uploaded, makes a reader refresh three times and still see the old paragraph, and makes you curl a page five minutes after a push, get a 404, and start suspecting the build. I have hit all three, and every one of them landed in the same place: the response headers.
I actually ran three rounds of tests. Round one pulled the real headers off my own site with curl and took them apart field by field. Round two started three minimal HTTP servers locally and let CacheControl 0.15.0 (on requests 2.34.2) hit them, counting how many times each one went back to the origin and which version of the body came back. Round three handed a real 304 to urllib and to requests to see how each one handles a success response with no body. All eight divergences below come from those three rounds. None of them were copied out of a spec.
TL;DR: The quotes in an ETag are syntax, not decoration — strip them and a 304 (0 bytes) degrades into a 200 with all 85,576 bytes. no-cache stores the response but revalidates every time; no-store is the one that really refuses to store; immutable skips validation entirely. My own 404 page ships no Cache-Control at all and the CDN caches it anyway. Neither a ?cb= query string nor Pragma: no-cache busts anything. One missing Vary line hands Chinese pages to English readers.
Start by taking one real response apart
Pick any published article on my site and curl -sI returns a set of headers like this (verbatim from the 11-16 article, request IDs removed):
HTTP/1.1 200 OK
Content-Length: 85576
Last-Modified: Mon, 16 Nov 2026 21:26:57 GMT
ETag: "6afb7521-14e48"
expires: Mon, 16 Nov 2026 22:21:50 GMT
Cache-Control: max-age=600
Age: 0
Vary: Accept-Encoding
X-Cache: MISS
Read line by line, and the owners are different:
| Field | Written by | What it decides |
|---|---|---|
Cache-Control: max-age=600 | origin (GitHub Pages) | for 600 seconds a local copy may be used without asking |
ETag | origin | what you send when you finally ask "did it change" |
expires | origin | the old-style expiry, here exactly Date plus 600 seconds |
Age: 0 | the shared cache (Fastly) | how long this copy has been sitting on the CDN |
X-Cache | the shared cache | whether this request hit or went back to origin |
Vary: Accept-Encoding | origin | compressed and uncompressed are two objects, do not swap them |
The expires value is 22:21:50 while the response Date is 22:11:50 — exactly 600 seconds apart. The same policy is written twice: once in the modern Cache-Control, once in the legacy expires. Why both, I get to in the fifth divergence.
Divergence one: the quotes around an ETag are syntax
Take that ETag and put it in If-None-Match four different ways, and the results are not "roughly the same":
| What goes in the request header | Status | Bytes on the wire |
|---|---|---|
If-None-Match: "6afb7521-14e48" | 304 | 0 |
If-None-Match: 6afb7521-14e48 (quotes stripped) | 200 | 85,576 |
If-None-Match: W/"6afb7521-14e48" | 304 | 0 |
If-None-Match: "deadbeef-1" | 200 | 85,576 |
The stripped-quotes line is the most expensive typo in this whole mechanism. The grammar is entity-tag = [ weak ] opaque-tag, and opaque-tag must be quoted. A bare string is not read as "the same value minus two characters" — it is read as a malformed header, and the entire header is ignored. The request degrades into an unconditional GET, the server dutifully ships all 85,576 bytes again, the status is 200, and nothing in any log says a word.
This bites hardest when you build headers yourself, or when some middle layer stores the ETag in a database and reads it back: JSON round-trips do not preserve the quotes for you, and plenty of template engines escape double quotes. The check is trivial — a conditional request must produce a 304. If you see a 200, what you sent was not a legal entity tag.
Two edges I also tested: If-None-Match: * returns 304 for a resource that exists (it means "match if any representation exists at all") and 404 for a path that does not; and a list, "aaa", "6afb7521-14e48", also returns 304, so multi-value parsing is fine.
Divergence two: the ETag carries the mtime and the byte count
That ETag looks random. It is not. Decode the two hex halves:
6afb7521 = 1794864417 -> 2026-11-16 21:26:57 UTC (exactly Last-Modified)
14e48 = 85576 (exactly Content-Length)
Three more samples agree: another article's ETag is "6afb7521-dd19" and 0xdd19 is 56,601, matching its Content-Length; the 404 page's ETag is "6afb7521-92d" and 0x92d is 2,349, matching the 404 body size; sitemap.xml carries "6afb7521-3efdc", which decodes to 258,012, again byte-for-byte.
The next part is inference, not measurement (I have no way to change the mtime of a file on the live host): this ETag is only as strong as second-resolution mtime plus total byte count. Two consequences —
- An edit that happens within the same second and leaves the total byte count unchanged produces the same ETag. On minified output that is not exotic: change one character, delete one space, same size.
- Rebuild on a different machine and every ETag on the site changes, even if not one character of content changed. Every client cache is invalidated for nothing.
So I treat it as a version number, not a content fingerprint. It is reliable for "is this the file I just pushed". It is not reliable for "the content did not change".
Divergence three: a weak validator lets two representations share one ETag
The same article, requested with and without Accept-Encoding, comes back as two different objects:
Accept-Encoding: gzip -> 47,144 bytes ETag: W/"6afb7521-14e48" Content-Encoding: gzip
Accept-Encoding: identity -> 85,576 bytes ETag: "6afb7521-14e48"
Two things worth remembering. The sizes differ by 45%, while the opaque-tag halves are identical, differing only by the W/ prefix. And conditional requests succeed in both directions: the weak tag from the compressed copy gets a 304 when asking for the uncompressed one, and the strong tag from the uncompressed copy gets a 304 when the request also says Accept-Encoding: gzip.
RFC 9111 section 4.3.4 says a 304 carrying a strong validator freshens every stored response holding that same strong validator, while a weak validator only freshens the most recent match. Nothing breaks here because Vary: Accept-Encoding splits the two representations into two cache objects. Which means Vary is what actually prevents cross-serving; the ETag only answers "did it change".
That matters for a multi-language site. If you serve Chinese and English from the same URL selected by Accept-Language, and you omit Vary: Accept-Language, the cache treats them as one object. Divergence eight measures exactly that.
Divergence four: no-cache stores and revalidates; only no-store refuses to store
This was the most counter-intuitive group. I stood up four endpoints, each with a different directive, and hit each one two or three times from its own cache directory, counting origin hits and recording which body version came back:
| Response header | Requests | Origin hits | Conditional requests | Body received |
|---|---|---|---|---|
Cache-Control: no-store + ETag | 2 | 2 | 0 | NOSTORE 1, then NOSTORE 2 |
Cache-Control: no-cache + ETag | 3 | 3 | 2 | NOCACHE 1 all three times |
Cache-Control: max-age=0, must-revalidate + ETag | 2 | 2 | 1 | MAXAGE0 1 both times |
Cache-Control: max-age=3600, immutable + ETag | 2 | 1 | 0 | IMMUTABLE 1 both times |
The no-store row: every request returns a different body, so nothing was ever written to disk. The no-cache row is the opposite: three requests hit the server three times, yet the body stays at the first version. It stored the response; it just asks before every use. RFC 9111 section 5.2.2.4 says the response MUST NOT be used to satisfy any other request without forwarding it for validation — the verb is "use", not "store". no-store, in 5.2.2.5, is the one that says MUST NOT store any part.
max-age=0, must-revalidate behaves identically to no-cache in my run: two requests, two origin hits, body never refreshed. Not a coincidence. max-age=0 makes it stale at birth, and must-revalidate forbids serving that stale copy, so the combined effect is "ask every time". The only difference is the extra safety rail against serving stale content.
immutable sits at the far end: two requests, one origin hit, and zero conditional requests. Even a reload or a back-navigation will not ask. That is fine for assets whose filenames contain a content hash. On an HTML document it pins the reader to an old version, with no error anywhere.
Divergence five: when Expires and Cache-Control disagree, the latter wins
Three combinations, three requests each:
| Header combination | Origin hits | What happened |
|---|---|---|
Expires one hour ahead + Cache-Control: max-age=0 | 3 | every request revalidated; Cache-Control wins |
Expires one hour ahead, nothing else | 1 | the last two served from cache |
Cache-Control: max-age=3600 + Expires one hour in the past | 1 | the last two served from cache; Cache-Control wins again |
The direction is one-way. With Cache-Control present, Expires is ignored. With Cache-Control absent, Expires is in charge. That is why my host sends both: to an old intermediary that only understands HTTP/1.0 semantics, Expires is the only line that works.
The real mistake is deleting just one of them. Drop Cache-Control, keep Expires, and it looks like you still have an expiry while you have actually switched to a different semantic. Drop Expires, keep Cache-Control, and the behaviour changes a third time. Change them together or not at all.
Divergence six: sending no Cache-Control is also a policy
The headers from python -m http.server look like this (measured locally, Python 3.13.14):
Server: SimpleHTTP/0.6 Python/3.13.14
Content-type: text/plain
Content-Length: 1100
Last-Modified: Mon, 16 Nov 2026 22:14:38 GMT
No Cache-Control, no ETag, only Last-Modified. But it does handle conditional requests: send If-Modified-Since and it returns 304. Which means your local preview's caching is decided entirely by the client's heuristics, and "did it change" is only resolvable to the second.
Production has the same hole. My 404 page ships no Cache-Control at all (not even expires), yet hitting the same 404 URL twice gives X-Cache: HIT with Age: 1 on the second try. No policy does not mean no caching; the CDN applies its own default. That is one real mechanism behind "the page I just published still returns 404 five minutes later" — what you are reading may be the 404 from before, not the absence of a build.
RFC 9111 section 4.2.2 lets a cache assign a heuristic freshness lifetime when no explicit expiry is present. That estimate is neither observable nor negotiable, which is exactly why it belongs in a release checklist as a known risk.
Divergence seven: neither a query string nor Pragma saves you
Two cache-busting tricks, and neither works.
Trick one is a query string. I hit the same article with four different random ?cb= values within a few seconds:
?cb= Age: 181 X-Cache: HIT
?cb= Age: 182 X-Cache: HIT
?cb= Age: 184 X-Cache: HIT
no query string Age: 185 X-Cache: HIT
Four different URLs, ages advancing in lockstep — they are all hitting the same cached object. On this host (GitHub Pages plus Fastly) the query string is not part of the cache key. Since it is the same object, ?cb= creates no new copy; it only makes the URL look different.
Trick two is Pragma: no-cache. Sent together with a correct If-None-Match, it still returns 304 — it is ignored outright. RFC 9111 section 5.4 says it plainly: the field was defined for HTTP/1.0 caches, and this specification deprecates Pragma.
The client side disagrees, which is the interesting part. In the same CacheControl client, /q?a=1 and /q?a=2 are two separate cache entries — the second one misses. So "is the query string part of the cache key" has opposite answers on a CDN and in a client library. A trick you design from one side's intuition spins idle on the other.
Divergence eight: a missing Vary hands you the wrong language
Two endpoints, both returning a body that varies with Accept-Language, both sending Cache-Control: max-age=300. The only difference is that one sends Vary: Accept-Language and the other does not. Request once with zh, then once with en:
| Endpoint | First (zh) | Second (en) | Second origin hit |
|---|---|---|---|
| no Vary | LANG=zh FIRST=True | LANG=zh FIRST=True | 0 (cache hit) |
| Vary present | LANG=zh FIRST=True | LANG=en FIRST=False | 1 |
The one without Vary hands the English request a Chinese body, without a single origin request, with no error and status 200. That is the whole mechanism of cross-language contamination: same URL, same cache key, and the cache concludes that what you asked for is what it already has.
For a site that publishes in Chinese, English and Japanese, the practical rule is short: if any layer — CDN, reverse proxy, corporate gateway — selects content on Accept-Language at the same URL, that layer must emit Vary: Accept-Language. Cache-Control cannot save you there. The same logic applies to Accept-Encoding: omit Vary and gzip bytes get delivered to a client that cannot decode them. My host has had that line all along, which is one of the few things I do not have to worry about.
A 304 is not a body: three clients, three reactions
Hand the same 304 to three clients and they behave nothing alike:
| Client | Result |
|---|---|
curl | status 304, 0 bytes downloaded, exit 0 |
urllib.request.urlopen | raises HTTPError: HTTP Error 304: Not Modified |
requests.get | status_code is 304, r.text is an empty string |
CacheControl (with a store) | returns the stored body and updates headers from the 304 |
urllib treats 304 as an exception because it routes everything that is not 2xx through HTTPError — and 304 is success semantics. This bites when you write your own health check: catch HTTPError, treat 304 as failure, and your check will alarm precisely when the content is unchanged, which is the healthiest state there is.
requests does not raise, but the body is empty. Calling r.json() next blows up — the traceback is in the next section. The correct handling is one sentence: treat 304 as success and reuse the copy you already have.
The caching client shows the canonical behaviour: it applies the 304 headers to the stored response (RFC 9111 section 4.3.4) and keeps the old body. I hit a max-age=2 endpoint three times, 2.5 seconds apart: the server took 3 hits and a conditional request went out each time, yet all three responses carried the first version of the body. Revalidating is not the same as re-downloading.
Extension directives are not protocol guarantees
Neither stale-while-revalidate nor immutable is in RFC 9111. The first comes from RFC 5861 (2010, Independent Submission, status Informational): it lets a cache hand out a stale copy while it revalidates in the background. The second is a de facto standard that browsers implement, but it is likewise absent from the RFC 9111 text.
What CacheControl 0.15.0 actually did: against an endpoint sending Cache-Control: max-age=1, stale-while-revalidate=600, I waited 1.6 seconds and requested again. It did not serve the stale copy first; it went straight back to origin (second server hit, from_cache False). The same library does honour immutable (two requests, one origin hit).
The conclusion is not "the directive is useless". It is that when you depend on an extension directive, you depend on one specific implementation. There is no interoperability guarantee, and one test run is faster than reading the docs.
What this means on my own site: three decisions
One, the ten minutes after a publish are real. max-age=600 means an old copy can live up to 600 seconds past a successful push. When a post-publish check returns a 404 or an old version, separate "the build has not finished" from "the cache has not expired". The first is a build-status question, the second is a wait. Neither is a reason to touch code.
Two, ?cb= is not a cache-busting tool. I measured it above: the cache key on this host excludes the query string. To decide whether production is serving the new version, compare the ETag (which is mtime plus size) or compare a string that appears exactly once in the body. This is also why I never compare byte counts after a publish: sitemap.xml is rebuilt on every build, so its size moves, while its Cache-Control is still 600.
Three, check Vary separately on a multi-language site. Chinese, English and Japanese pages are three different URLs, so that part is fine. But the moment one layer selects by Accept-Language at a single URL, Vary has to go out with it. The check is one command: curl -sI and look for the line.
This way of reading "the string looks identical, the behaviour is not, and nothing errors" is the same one I used in Windows path semantics. The same family includes YAML configs that read the wrong value and nine silent shell failures. If you also maintain an automated publishing chain, the three read well together — and if you are wiring up the deploy step itself, automating deployments with GitHub Actions is where those status codes come from.
Errors you will actually see
Error one: urllib.error.HTTPError: HTTP Error 304: Not Modified
Traceback (most recent call last):
File "check.py", line 12, in main
with urllib.request.urlopen(req, timeout=5) as r:
urllib.error.HTTPError: HTTP Error 304: Not Modified
Cause: urllib funnels every non-2xx response into HTTPError, and 304 is still raised even though it means success. Fix: catch it explicitly and treat it as "content unchanged" rather than failure.
except urllib.error.HTTPError as e:
if e.code == 304:
return cached_copy # success, not failure
raise
Error two: json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)
Cause: requests returns status 304 with an empty body, and the next r.json() parses an empty string. Fix: branch on 304 first and return the local copy; never call .json() unconditionally on a response that can be a 304.
r = sess.get(url, headers={"If-None-Match": etag})
if r.status_code == 304:
return local_cache
return r.json()
Error three: ImportError: NOTE: In order to use the FileCache you must have filelock installed
Full text:
NOTE: In order to use the FileCache you must have
filelock installed. You can install it via pip:
pip install cachecontrol[filecache]
Cause: cachecontrol 0.15.0 keeps filelock as an optional dependency, and FileCache raises the moment it is actually used. Fix: install cachecontrol[filecache], or switch to in-memory DictCache — but that one is not shared across processes, so do not use it to prove "the other process got a cache hit".
Symptom four: conditional requests keep returning 200 instead of 304. In order of likelihood: the ETag lost its quotes (divergence one), you sent If-Modified-Since with a local clock ahead of Last-Modified, or Last-Modified only resolves to the second and your edit landed inside the same second. The diagnostic is to echo the header you sent, then echo the ETag the server returned, and compare them byte for byte.
Where this stops
- The network side was measured only against my own site (GitHub Pages plus Fastly), using a handful of articles from 11-16 and 11-17, one 404 page and
sitemap.xml. Cloudflare, nginx and CloudFront have different defaults; do not copy these numbers across. - The client side was measured only with CacheControl 0.15.0 on requests 2.34.2 (CPython 3.13.14, Windows 11). Browsers were not tested. Service workers were not tested.
- Range requests and
If-Range, HTTP/3,stale-if-error, and the split betweenprivateand shared caches are all out of scope. - Divergence two is a decoded inference. I could not modify mtimes on the live host to manufacture an actual same-second, same-size collision.
This article contains no affiliate links of any kind.
FAQ
Q: Does no-cache tell the browser not to cache?
No. It says "store it, but ask me before every use". The directive that actually refuses to store is no-store — in my run it returned a different body every single time, while no-cache kept serving the first body across three requests. The name reads backwards, and that is the most common source of confusion around it.
Q: I changed the CSS but the filename is the same. How do I get everyone onto the new one?
The reliable answer is to change the filename (with a content hash) and pair it with immutable. If you cannot rename, at least give max-age a short value and keep the ETag so caches revalidate. The least reliable option is a query string — on this host the cache key ignores it, so appending one changes nothing.
Q: Does a 304 restart the max-age clock on the CDN?
Two layers, two answers. On the CDN, Age kept climbing across a 304 in my tests (26 to 27) — it tracks the object's age and is not reset by a revalidation. On the client, RFC 9111 section 4.3.4 has the cache apply the 304 headers to the stored response, so freshness is recomputed from that validation. Mixing the two layers is how people arrive at the false conclusion that a cached page renews itself forever every ten minutes.
Q: Why is local preview fine while production serves the old version?
Because python -m http.server sends no Cache-Control at all, so the browser falls back to heuristic freshness and usually revalidates immediately. Production explicitly says max-age=600, so it does not ask for ten minutes. Different policies, different symptoms. Start the investigation with curl -sI, not with clearing the browser cache.
👉 Join Xiaomi MiMo Platform: Leading AI model platform with cost-effective inference
👉 Join Aliyun AI: Top AI products with exclusive coupons for business innovation
📌 This article was AI-assisted generated and human-reviewed | TechPassive — An AI-driven content testing site focused on real tool reviews
🔗 Recommended Tools
These are carefully selected tools. Using our affiliate links supports us to keep producing quality content:
As an Amazon Associate, I earn from qualifying purchases at no extra cost to you.