HTTP Caching Headers: Cache-Control Explained
Cache-Control, ETag and Vary decide what a browser and a CDN cache. Learn the directives, the revalidation, and the common mistakes.
By Velloreth
The main directive
Cache-Control: public, max-age=31536000, immutable
max-age is the freshness lifetime in seconds. Within that time the browser uses the cached copy without asking the server.
public allows a shared cache such as a CDN to store it.
private allows only the browser to store it, which is the right choice for a user-specific response.
immutable tells the browser never to revalidate, which is safe for a hashed filename.
The directives
| Directive | Meaning |
|---|---|
max-age=N | Fresh for N seconds |
s-maxage=N | Fresh for N seconds in a shared cache |
no-cache | Revalidate before using |
no-store | Do not store at all |
public | A shared cache may store it |
private | Only the browser may store it |
immutable | Never revalidate |
must-revalidate | Revalidate once stale |
stale-while-revalidate=N | Serve stale for N seconds while revalidating |
no-cache is the most misunderstood. It does not mean “do not cache”; it means “revalidate before using”. The name is a historical accident.
no-store is the directive for sensitive data, such as a bank statement.
A caching strategy
A hashed static asset — cache for a year.
Cache-Control: public, max-age=31536000, immutable
The filename contains a content hash, so a change produces a new URL. The old URL is never requested again.
An HTML page — revalidate every time.
Cache-Control: no-cache
The page may be stored, but the browser revalidates, so a deploy is visible immediately.
An API response — a short cache with a stale window.
Cache-Control: public, max-age=60, stale-while-revalidate=300
The response is fresh for a minute, and a stale copy is served for five minutes while a revalidation happens in the background.
A user-specific response — private, and short.
Cache-Control: private, max-age=0, must-revalidate
Revalidation
An ETag is a fingerprint of the content.
ETag: "abc123"
The browser sends it on the next request:
If-None-Match: "abc123"
If the content is unchanged, the server returns:
HTTP/1.1 304 Not Modified
A 304 has no body, so the revalidation is cheap.
Last-Modified works the same way with If-Modified-Since, though it is less precise than an ETag.
A weak ETag (W/"abc123") means the content is semantically equivalent, which allows a proxy to compress it differently.
The Vary header
Vary tells a shared cache which request headers affect the response.
Vary: Accept-Encoding
Without it, a cache may serve a gzipped response to a client that cannot decompress it, or the reverse.
Vary: Accept-Encoding is the most common and is usually added by the server automatically.
Vary: Cookie is a warning sign: it means the response depends on a cookie, so a shared cache cannot cache it effectively. A user-specific response should be private instead.
A missing Vary on a user-specific response is a serious bug, because a CDN may serve one user’s response to another.
Common mistakes
no-cache on a static asset. It forces a revalidation on every request, which defeats the cache.
no-store on everything. It disables the cache entirely, which is a performance problem.
A long max-age on an HTML page. A deploy is invisible until the cache expires.
A long max-age on a non-hashed asset. The content changes but the URL does not, so the old version is served.
No Vary on a response that depends on a header. A cache serves the wrong variant.
A private response cached publicly. One user sees another’s data.
An ETag that changes on every request. The revalidation always returns a 200, so the cache is useless.
Caching in a static site
A static site has the simplest strategy.
The HTML — revalidate, so a deploy is immediate.
Cache-Control: public, max-age=0, must-revalidate
The hashed assets — cache for a year.
Cache-Control: public, max-age=31536000, immutable
An image without a hash — a moderate cache.
Cache-Control: public, max-age=86400
A CDN in front caches the HTML at the edge, and a purge on deploy makes the new version visible.
Debugging a caching problem
A caching problem is usually one of two symptoms: a change that does not appear, or a stale response served to the wrong user. The first is diagnosed by looking at the response headers in the network panel and checking the age and the cache-control directive. A long max-age on an HTML page is the usual cause, and the fix is to revalidate the HTML and cache only the hashed assets. The second is more serious, and it is diagnosed by checking the Vary header and the private directive on a user-specific response. A response that depends on a cookie and is cached publicly is a data leak, and the fix is to mark it private or to key the cache by the user. A CDN purge is the escape hatch when a stale response is already in the edge cache, and it is worth knowing how to trigger one before a deploy rather than during an incident.
Practical guidance
- Use a hashed filename for a long cache.
- Revalidate the HTML.
- Use
no-storefor sensitive data. - Remember
no-cachemeans revalidate. - Add an ETag for a revalidation.
- Set
Varywhen the response depends on a header. - Use
privatefor a user-specific response. - Use
stale-while-revalidatefor a background refresh. - Purge the CDN on deploy.
For the related guides, see etags-explained and how-cdns-actually-work. For the broader context, core-web-vitals-guide and caching-strategies-explained.
Quotable summary
Cache-Control is the main directive and max-age sets the freshness lifetime in seconds, while no-cache means revalidate before using rather than do not cache, and no-store means do not cache at all. immutable is safe for a hashed filename because the content never changes at that URL, which is why a hashed asset can be cached for a year. An ETag enables a conditional request, so a revalidation returns a 304 with no body, which makes the check cheap. Vary tells a shared cache which request headers change the response, and a missing Vary on a user-specific response is a serious bug because a CDN may serve one user’s response to another.