Why Your Users Still See Old Code: 5 Counter-Intuitive Truths About HTTP Caching

You just pushed a critical bug fix to production. The build pipeline passed, unit tests are green, and your origin server is successfully running the updated application code.

Yet, reports immediately flood in from users claiming the bug is still present. When you inspect their live sessions, you confirm the maddening conflict: your deployment succeeded on the origin server, but the actual user experience remains stuck on the old version.

Where is this stale response originating, and why doesn't updating the origin server instantly fix what the user sees? To solve this mystery, software engineers must look beyond application code and examine the mechanics of the HTTP caching pipeline.

Takeaway 1: Updating the Origin Server Doesn't Clear the Network

When a client requests a web asset, the request rarely travels straight to the origin server in isolation. Modern application architectures rely on a multi-tiered request flow:

Browser Cache → CDN Cache → Reverse Proxy Cache → Origin Server

(Note that this multi-tiered architecture refers strictly to HTTP-level caching mechanisms, distinct from DNS resolution or domain propagation delays.)

An application response can be stored and reused at any of these intermediate network layers. When an origin server returns a header like Cache-Control: public, max-age=3600, it defines two critical rules:

• public permits any intermediate shared cache (such as a CDN or reverse proxy) to store the payload, while
• max-age=3600 establishes a freshness lifetime of 3,600 seconds (one hour). During this timeframe, caches are explicitly authorized to serve their stored copy without contacting the origin.

"An application response may be cached at multiple points between the origin and the user. Updating the origin does not automatically remove every previously cached response."

Engineers frequently fall into the trap of assuming a successful origin deployment acts as an immediate global reset. However, if a cached representation downstream is still considered fresh according to its max-age freshness lifetime, that layer will continue serving old content autonomously—completely oblivious to the updated code sitting on your origin server.

Takeaway 2: no-cache Does Not Mean "Do Not Cache"

One of the most widespread misconceptions in web performance stems from the intuitive—but misleading—naming of Cache-Control directives. Many developers configure no-cache assuming it prevents responses from being stored entirely. In HTTP protocol specifications, its behavior is fundamentally different:

• Cache-Control: no-cache: Permits caches to store the response, but explicitly requires them to validate the cached representation with the origin server (revalidation) before reusing it.
• Cache-Control: no-store: Explicitly instructs caches never to store the response in any cache, anywhere.

Confusing these two directives introduces severe operational trade-offs. When using no-cache, caches retain local copies of the asset. Upon receiving a user request, the cache sends a conditional validation check to the origin; if the source hasn't changed, the origin returns a lightweight 304 Not Modified response without a payload body, saving significant network bandwidth.

Conversely, using no-store under the mistaken belief that it simply forces freshness checks prevents storage entirely. This forces full HTTP 200 OK transfers with complete payload downloads on every single request, eliminating the bandwidth benefits of HTTP caching.

Takeaway 3: ETags Are Validation Tools, Not Automatic Cache Purges

Entity Tags (ETag) provide a mechanism for conditional HTTP requests, allowing caches and clients to verify whether a stored representation is still current without re-downloading the entire asset.

The standard validation flow operates as follows:

1. The origin server delivers a response with an ETag header: ETag: "version-42".
2. On a subsequent request, the client or intermediate cache sends a conditional header: If-None-Match: "version-42".
3. The origin server evaluates the state of the resource:
   • If the content has not changed, the server returns an HTTP 304 Not Modified status code with no response body.
   • If the content has changed, the server returns an HTTP 200 OK status code along with the new payload and a new ETag string.

Crucially, ETags function strictly as passive validators during client-initiated revalidation requests. They are not proactive invalidation mechanisms capable of pushing updates or purging stale representations across CDNs and intermediary caches automatically.

Takeaway 4: Content-Hashing Is the Secret to Aggressive Frontend Caching

To cache static frontend assets aggressively while ensuring users receive updates immediately upon deployment, applications must leverage content-hashed filenames.

With content hashing, the asset filename is derived directly from the cryptographic hash of its source code:

• Old Version: app.a81f32.js
• New Version: app.c92d10.js

When source code changes, the resulting filename changes. Because the updated filename represents an entirely new URL, browsers and CDNs can safely cache static assets long-term under high max-age values without risk of serving stale code under that specific address.

However, this architecture hinges on how the entry point is handled. Because the HTML document serves as the control point that bootstraps and references all content-hashed asset URLs, caching HTML long-term breaks the atomic deployment chain. If an HTML document is cached aggressively without revalidation (e.g., lacking no-cache), the browser will continue reading the cached HTML file and requesting the old asset URLs (app.a81f32.js), rendering the new build (app.c92d10.js) completely invisible to the user.

Takeaway 5: Stop Guessing—Inspect Your HTTP Response Headers First

Altering caching configurations blindly or issuing immediate full-cache purges often fails to resolve stale content issues and can place unexpected, overwhelming load on origin infrastructure. Before modifying configuration settings, engineers should open browser Developer Tools to inspect response headers and pinpoint precisely which layer served the cached content.

Key fields and headers to inspect include:

• Cache-Control: Directives governing freshness lifetime and storage rules (e.g., public, max-age, no-cache, no-store).
• ETag: The validator string returned by the origin server.
• Age: Indicates the duration in seconds that a representation has resided in an intermediate CDN or proxy cache. When evaluated against max-age (e.g., a header set to max-age=3600 alongside Age: 3500), it reveals that only 100 seconds of freshness remain at that layer before revalidation is triggered.
• CDN-Specific Cache Headers: Headers (such as x-cache, cf-cache-status, or x-served-by) indicating cache hits, misses, or edge execution status.
• HTTP Status Codes: Verifying whether the request yielded a 200 OK full payload transfer or a 304 Not Modified revalidation check.

Identifying the exact caching layer responsible for serving a stale representation ensures targeted remediation rather than trial-and-error configuration changes.

Conclusion: Respect the Cache Pipeline

Delivering reliable web applications requires viewing HTTP caching as a deliberate, end-to-end network pipeline rather than a simple origin configuration setting.

"Updating the origin does not automatically update every cached copy. Understand cache freshness, validation and invalidation before blaming the deployment."

Take a moment to audit your current delivery pipeline: Are your Cache-Control headers accurately enforcing your intended validation policies, and are your HTML documents configured to prevent stale asset references from breaking your deployments?

---

Originally published on gokairo.dev.