Skip to content
Velloreth
Web Development 5 min read

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

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

DirectiveMeaning
max-age=NFresh for N seconds
s-maxage=NFresh for N seconds in a shared cache
no-cacheRevalidate before using
no-storeDo not store at all
publicA shared cache may store it
privateOnly the browser may store it
immutableNever revalidate
must-revalidateRevalidate once stale
stale-while-revalidate=NServe 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-store for sensitive data.
  • Remember no-cache means revalidate.
  • Add an ETag for a revalidation.
  • Set Vary when the response depends on a header.
  • Use private for a user-specific response.
  • Use stale-while-revalidate for 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.

Frequently asked questions

What is the difference between no-cache and no-store?
no-cache means the response may be stored but must be revalidated before use. no-store means it must not be stored at all, which is the right directive for sensitive data.
What is max-age?
The freshness lifetime in seconds. Within that time the browser uses the cached copy without asking the server.
What is s-maxage?
The freshness lifetime for a shared cache such as a CDN, which overrides max-age for that cache.
What is an ETag?
A fingerprint of the response content. The browser sends it in If-None-Match, and the server returns 304 Not Modified if the content is unchanged.
What is the Vary header for?
It tells a shared cache which request headers affect the response, such as Accept-Encoding or Cookie. Without it, a cache may serve one user's response to another.
How do I cache a static asset for a year?
Use a hashed filename and Cache-Control: public, max-age=31536000, immutable. The hash changes when the content changes, so the URL is unique per version.