When a browser or CDN serves an older response, the fastest fix is to identify which cache supplied it, read the response headers, and then choose a caching policy that matches the resource. This HTTP Cache-Control headers guide provides a reusable workflow for debugging stale assets, HTML, API responses, and CDN content, with practical configuration patterns for common deployments.
Overview
HTTP caching is layered. A response may be stored by the browser, a service worker, a corporate proxy, a reverse proxy, a CDN, or another intermediary before it reaches the origin server. A stale response is therefore not automatically an application bug. The key question is: which layer returned the response, and was that layer allowed to do so?
Start by inspecting the response in your browser's Network panel or with a command such as:
curl -I https://example.com/app.js
Look for Cache-Control, Age, ETag, Last-Modified, Expires, and any provider-specific headers such as Via, X-Cache, or CF-Cache-Status. These headers are clues, not a universal naming system: intermediary headers vary by CDN and infrastructure provider, and a browser cache may not expose an Age value at all.
The most important distinction is between freshness and revalidation:
- Fresh: the cache can reuse the stored response without contacting the origin.
- Stale: the stored response is beyond its freshness lifetime and normally needs validation or replacement.
- Revalidation: the client asks whether its stored response is still valid, usually using an
ETagorLast-Modifiedvalue.
no-cache does not mean “do not store.” It means a stored response must be revalidated before reuse. no-store is the stronger instruction not to store the response. Confusing these directives is a common cause of either stale content or unnecessarily slow applications.
Cache-Control directives at a glance
| Directive | Typical meaning | Useful for |
|---|---|---|
max-age=seconds | Allows a browser or shared cache to consider the response fresh for the stated period. | Stable resources with a known update cadence. |
s-maxage=seconds | Sets a freshness lifetime for shared caches and can take precedence over max-age for them. | CDN or reverse-proxy caching of public responses. |
no-cache | Permits storage but requires validation before reuse. | HTML or APIs where conditional requests are acceptable. |
no-store | Instructs caches not to store the response. | Private, sensitive, or highly transient responses. |
public | Indicates that a response may be stored by shared caches, subject to other rules. | Public assets or deliberately cacheable API responses. |
private | Restricts storage to a private cache such as a user's browser. | Responses personalized for one user. |
must-revalidate | Requires revalidation once the response is stale rather than serving it as a stale response. | Data where stale content is not acceptable. |
stale-while-revalidate=seconds | Allows a cache to serve a stale response briefly while it fetches a newer one, where supported and configured. | Public content where low latency matters more than an occasional short delay in freshness. |
immutable | Signals that a fresh response will not change during its freshness lifetime. | Versioned or content-hashed static assets. |
Checklist by scenario
Scenario 1: A browser displays an old HTML page
- Open the page in a private window or disable the browser cache while DevTools is open. This separates a local browser-cache issue from an upstream issue.
- Inspect the document request, not only the JavaScript and CSS requests.
- Record the response's
Cache-Control,Age,ETag, andLast-Modifiedvalues. - Compare a normal request with a request containing
Cache-Control: no-cache. If the second response differs, a cache or revalidation path is involved. - Check whether a service worker is intercepting the request. Its cache storage and update lifecycle are separate from ordinary HTTP cache behavior.
For frequently changing HTML, a conservative pattern is:
Cache-Control: no-cache
This allows the browser to retain the response but asks it to validate before using it. If the page contains user-specific or sensitive information, use a policy appropriate to that data, such as private, no-store where storage must be avoided.
Scenario 2: A new JavaScript or CSS asset is not appearing
For production builds, prefer content-hashed filenames such as app.8f31c.js rather than repeatedly replacing app.js. When the file content changes, the URL changes as well, so a previously cached URL cannot silently point to the new content.
Cache-Control: public, max-age=31536000, immutable
Use this only when the URL is genuinely versioned or content-hashed. Do not apply a long immutable lifetime to an unversioned filename that is overwritten during deployment. Also ensure the HTML document is refreshed or revalidated so it can discover the new asset filename.
If an asset URL cannot be changed, use a shorter lifetime or purge the relevant CDN object after deployment. Query-string versioning can work, but confirm that the CDN and origin treat the query string consistently.
Scenario 3: A CDN serves an old response
- Request the same URL from more than one location if possible. A single old response may represent one edge location rather than the whole CDN.
- Inspect CDN indicators such as a cache hit, miss, pass, or revalidation result. Names and meanings are provider-specific.
- Compare the CDN response with a direct origin response, using a temporary origin hostname or an authenticated diagnostic route where appropriate.
- Check the CDN's cache key: host, path, query string, selected headers, cookies, and content encoding can all affect which object is returned.
- Confirm whether a deployment changed the origin response but left the cached object untouched.
A common public-content pattern is:
Cache-Control: public, max-age=60, s-maxage=3600, stale-while-revalidate=60
This gives browsers a shorter freshness period while allowing a shared cache to retain the object longer. The exact values should reflect how quickly the content must change and whether briefly stale content is acceptable. If you purge objects during deployment, treat purge completion as an operational step and verify it with a fresh request.
Scenario 4: An API returns old or inconsistent data
First classify the endpoint. A public, identical response may be cacheable; a response containing account-specific data usually should not be shared. For user-specific responses, consider:
Cache-Control: private, no-cache
This allows a private cache to store the response while requiring validation. For sensitive responses or endpoints where even local storage is inappropriate, use:
Cache-Control: private, no-store
For public API data, define a deliberate cache key and vary behavior carefully. Responses that change based on authorization, cookies, locale, or request headers need particular attention. An incorrect shared-cache configuration can return one variant to another client, so do not make an API publicly cacheable merely because it is fast to serve.
Scenario 5: The origin supports conditional requests
An ETag identifies a representation, while Last-Modified provides a time-based validator. On revalidation, the client may send If-None-Match or If-Modified-Since. If the representation has not changed, the server can return 304 Not Modified without sending the full body.
Verify that your deployment, compression layer, and application do not generate unstable validators for unchanged content. Also remember that a validator does not force a cache to revalidate; the response's freshness directives determine when validation is needed.
What to double-check
- Request versus response headers: a request header such as
Cache-Control: no-cacheis a debugging instruction from the client; it does not rewrite the server's caching policy. - Multiple Cache-Control headers: inspect how your server and CDN combine them. Conflicting values are difficult to reason about and may be normalized differently by intermediaries.
- Deployment order: publish new hashed assets before deploying HTML that references them. Avoid deleting an asset while an older HTML response can still reference it.
- Compression and variants: confirm that compressed and uncompressed responses are represented consistently and that the cache key accounts for content negotiation where needed.
- Cookies and authorization: do not allow shared caching of personalized responses unless the cache policy and key explicitly isolate users.
- Origin and edge clocks: time-based headers can be misleading when diagnosing a single request. Compare timestamps, age values, and request paths rather than relying on one header.
- Framework defaults: static-file middleware, server adapters, hosting platforms, and CDNs may add or override headers. Inspect the deployed response rather than assuming local development behavior matches production.
For Node.js applications, set policies close to the route or static-file configuration that owns the response, then verify them at the public URL. If the application is containerized, also check the reverse proxy in front of it. A production Node.js deployment may include several layers; the final response is the authority for browser debugging. See the Dockerizing a Node.js application guide for related deployment and health-check considerations.
Express example
app.use('/assets', express.static('dist/assets', {
maxAge: '1y',
immutable: true
}));
app.get('/api/catalog', (req, res) => {
res.set('Cache-Control', 'public, max-age=60, s-maxage=300');
res.json(catalog);
});
The asset example assumes the build produces versioned filenames. The API example assumes the catalog is public and identical for all clients; change it if authentication, cookies, or personalization affect the response.
Nginx example
location /assets/ {
add_header Cache-Control "public, max-age=31536000, immutable";
}
location = / {
add_header Cache-Control "no-cache";
}
Test the effective headers after Nginx, the application server, and any CDN have processed the response. Configuration inheritance and another layer's header rules can change the result.
Common mistakes
- Using
no-cachewhen you meanno-store: this leaves the response eligible for storage, although it must be validated before reuse. - Using long-lived caching for mutable filenames: a CDN cannot know that an overwritten
main.jshas changed until it revalidates or is purged. - Patching stale HTML by purging only assets: the old HTML may still reference an old asset URL or an old API endpoint.
- Assuming Ctrl or Cmd + Refresh proves the cache is fixed: forced reload behavior is a diagnostic action, not the experience of ordinary visitors.
- Reading an
Ageheader as proof of browser caching: it generally describes time in a shared cache and may be absent from browser-served responses. - Adding
immutableto everything: it is a good fit for truly versioned assets, not for HTML, mutable API data, or filenames replaced in place. - Purging without changing the cache strategy: a purge fixes the current object but does not prevent the same stale-content problem on the next deployment.
- Ignoring service workers: a service worker can return an entry from Cache Storage even when the network response headers look correct.
When to revisit
Revisit this checklist before a major deployment, after changing CDN rules, when introducing a service worker, and whenever a framework or hosting configuration changes its default headers. It is also worth reviewing before seasonal traffic or content-planning cycles, when a longer cache lifetime may improve performance but stale content may become more visible.
Use this short runbook during an incident:
- Capture the exact URL, request method, time, and relevant request headers.
- Capture response headers from the public URL and, if safe, from the origin.
- Identify whether the response came from the browser, service worker, CDN, reverse proxy, or origin.
- Compare the response body and validators with the version expected from the current deployment.
- Decide whether to revalidate, purge, change the URL, or correct the caching directive.
- Repeat the test from a clean browser context and at least one separate network path.
- Record the chosen policy beside the deployment configuration so the next change does not undo it.
The durable fix is usually a clear separation: revalidate HTML, version static assets, cache only public API responses deliberately, and keep personalized data private. Once those rules are explicit, HTTP cache debugging becomes a repeatable inspection task rather than a sequence of forced refreshes and unexplained CDN purges.