Cache busting

Cache busting is the technique of changing the URL of a static asset, by embedding a content hash or version in its filename or query string, whenever the asset changes, so that browsers and CDNs that cached the old version fetch the new one instead of serving what they already hold. It is why a deployed fix can still be invisible to a tester whose browser kept the old file.

The longer version

Browsers cache scripts, stylesheets and images so a return visit does not download them again, and the server tells them how long the copy stays valid. A file that keeps its name across deployments is served from that cache until the copy expires, regardless of what the server now holds. Cache busting sidesteps the expiry by giving the changed file a new name, typically the file's own content hash, so the URL the HTML references is one the browser has never seen. Build tools do this automatically and rewrite the references; the hashed name can then be cached indefinitely without risk.

The neighbour is cache invalidation, which is the server or CDN side: telling a cache to drop an entry it holds. Busting works from the other direction by never asking for the stale entry. Query-string versioning, appending a version parameter to a stable filename, is the older and weaker form, because some intermediate caches ignore query strings and the parameter is easy to forget to change. A hard refresh is not cache busting; it is a tester bypassing the cache on one machine, which proves nothing about what other users receive.

In testing, the symptom is the bug that is fixed and still reproduces. The developer deployed, the tester loads the page, the old script runs from cache and the ticket bounces back as not fixed. Or the HTML page itself was cached, so a returning user's browser asks for the hashed files the new deployment deleted, and the page renders unstyled for everyone who held the old page. A report that records which file version the browser loaded, or the request timings that show a resource was served from cache, ends the argument in one look.

Common questions

What is the difference between cache busting and cache invalidation?

Cache invalidation removes or expires an entry that a cache already holds, from the server or CDN side. Cache busting changes the asset's URL so the stale entry is never requested. Busting is the standard for build output, since it works with every cache in the chain; invalidation is used for content that keeps its URL, such as HTML pages.

Why can a tester still see a bug after it has been fixed and deployed?

The browser or a CDN between the tester and the server is still serving the previous version of a script or stylesheet under its old name. If the deployment did not change the asset's URL, the cached copy stays valid until it expires. Checking which file version the page loaded, rather than clearing the cache and moving on, shows whether the release itself is wrong.

Is a query string enough for cache busting?

A query string version works with most browser caches but not with every CDN or proxy, some of which ignore query strings or refuse to cache URLs that carry them. Putting a content hash in the filename is the reliable form, because every cache treats it as a different resource and the hash changes only when the content does.

How do you check whether a page loaded a cached file?

Open the network panel in developer tools, reload without bypassing the cache, and read the size column: an entry served from memory or disk cache says so instead of showing a transfer size. Then compare the filename hash against the one in the new deployment. A hard reload proves the fix exists but destroys the evidence of what other users are receiving.

Does cache busting apply to HTML pages?

HTML pages keep a stable URL, so a hash cannot be put in their name; they are served with short or no-cache headers and invalidated from the server side instead. The hashed scripts and stylesheets they reference are cached for a long time. A cached HTML page pointing at hashed assets a new deployment deleted is the classic unstyled page after a release.

Bug reports that arrive ready to triage.

Collect replay, console, network and browser context with the Free plan.

<script src="…/widget.js" data-key="pb_pub_…">