The Deployment Succeeded — So Why Do Users Still See the Old Website?

The deployment is green. The homepage looks correct on your machine. Yet customers, colleagues, or the sales team report: “I still see the old version.”

That is often not an exotic browser glitch but a cache and release problem. Old HTML meets new assets, a CDN serves inconsistent versions, or personalized responses are stored under the wrong cache key. The website is online — but not reliably current.

Why a successful build does not prove a successful release

Several layers sit between the repository and the browser: hosting, reverse proxies, a CDN, shared caches, the browser cache, and possibly a service worker. Every layer may store responses. That is useful until the caching rules no longer match the content.

A common failure:

1. index.html is cached for too long.
2. A deployment creates JavaScript files with new hashes.
3. Some users continue to receive the old HTML.
4. The older referenced assets have already been removed.
5. The page loads partially, turns blank, or loses functionality.

The reverse can happen too: new HTML receives old, unversioned files from the same URLs.

The simple rule many setups break

Mutable documents and immutable assets need different cache strategies.

For versioned files such as app.8f3a1c.js, a long cache lifetime makes sense. When the content changes, the URL changes. MDN describes this cache-busting pattern as the basis for storing such resources for a long time and marking them immutable.

HTML, API responses, configuration, and personalized pages need more deliberate rules. no-cache does not mean “never store”; it means a stored response must be validated before reuse. Truly sensitive content may require no-store.

One blanket policy for the entire domain is therefore usually wrong.

Five signs your cache strategy is fragile

1. Files change but their URLs do not

If /assets/app.js is overwritten on every deployment while being cached for a long time, old and new versions can coexist unpredictably.

2. HTML is cached as long as static assets

A one-year lifetime can be reasonable for hashed assets. It is usually dangerous for HTML that changes regularly.

3. Nobody knows the delivered headers

“Our CDN handles it” is not an operational answer. What matters is the response: Cache-Control, Age, ETag, Last-Modified, Vary, and provider-specific cache-status headers.

4. Language or content variants share one cache entry

When a response depends on Accept-Language, Accept-Encoding, or another request header, the cache must know which inputs influenced the content. The Vary header controls that separation. Without it, the wrong variant may be served.

5. Old assets are deleted immediately

Even with correctly hashed files, older HTML documents may remain in circulation for a while. Removing their assets immediately creates avoidable 404 and chunk-load errors.

A practical cache check after every deployment

Do not stop at confirming that a URL returns status 200. Test the release as a user journey.

Documents

• Does HTML use an appropriate revalidation strategy?
• Does the content actually change after deployment?
• Are ETag or Last-Modified values consistent?
• Is personalized HTML accidentally marked public?
• Do sensitive responses use appropriate private or non-storage directives?

Static assets

• Do filenames include a content or build hash?
• Are hashed files served with a long lifetime and, where appropriate, immutable?
• Are older assets retained during a safe transition period?
• Do HTML and manifests reference files that exist?

CDN and variants

• Does Age reveal unexpectedly old responses?
• Is the cache key complete?
• Does Vary match language, compression, or content variants?
• Are error pages or authenticated responses cached publicly by mistake?
• Can specific content be invalidated safely?

Browser and service worker

• Does an existing service worker update reliably?
• Can users remain trapped in an old application shell?
• Does the release work in a normal browser session, not only after a hard reload?
• Was it tested without an authenticated admin session and from a second connection?

A hard reload is not a fix

If an issue disappears only after users clear their cache manually, the release process is broken.

A hard reload can help with diagnosis. It does not prove that ordinary visitors receive the correct version automatically. The useful question is: Does a returning visitor receive one consistent release after deployment?

How to make caching release-safe

A robust approach usually includes:

1. Hashed, immutable assets. New content receives a new URL.
2. Short-lived or revalidated HTML. Documents must not hide releases for days.
3. Atomic deployments. HTML and assets belong to the same release.
4. A transition window for older assets. Existing documents must not point into a void.
5. Explicit cache keys. Language, compression, and other variants are separated correctly.
6. Targeted invalidation. Purge only what actually changed.
7. Release smoke tests. Load HTML, verify referenced assets, and test critical journeys without forcing a reload.
8. Observability. Track 404 spikes, chunk-load errors, and unusual cache-status responses.

What Website-Pflichtencheck would inspect

A Website-Pflichtencheck does not review one header in isolation. The important part is the interaction between hosting, CDN, build output, HTML, assets, API responses, service workers, and the deployment process.

A review can examine:

• which content is public, private, or not cacheable
• whether hashed assets are genuinely immutable
• whether older releases can expire safely
• whether ETag, Vary, and revalidation are used coherently
• whether personalized or sensitive responses could enter shared caches
• whether a deployment works consistently without a hard reload
• whether release failures become visible and reproducible

Caching should make a website faster. It should not leave different users living in different versions of the same product.

If “works on my machine” regularly ends with “please clear your cache,” you do not need a better support phrase. You need a verifiable cache and release process.