Why a deploy looks broken in one browser but fine in another

If a freshly deployed page looks wrong in one browser tab but right in a private window, the server is probably fine and the browser is running the previous copy of a CSS or JavaScript file. The HTML came from the new deploy; the stylesheet came from the cache the browser filled before it. The fix is to serve each file from a URL that changes when the file's contents change.

This is common when a site is assembled by hand — a small server rendering templates, a static folder behind a container — rather than by a framework or static host that fingerprints assets for you.

What the mismatch looks like

The two files arrive from different deployments, so what you see is one half of each:

The tell is the comparison: the normal window is broken; a private or incognito window, which starts with an empty cache, is correct. A hard refresh usually fixes the window for now — and that is exactly the trap, because the next visitor with an old cache sees the broken version again.

Check what the browser actually received

  1. Open the developer tools' Network panel, reload, and look at the CSS and JS requests. A request served from the browser's disk or memory cache, or answered 304 Not Modified, is a candidate.
  2. Compare the two windows side by side, or fetch the files directly:
# What the server publishes, without any browser cache in the way
curl -sI https://example.com/styles.css

# Ask for a URL the browser has never requested
curl -sI "https://example.com/styles.css?cachecheck=$(date +%s)"

If the first command's file is the old one, the deploy itself did not roll out — check the build status and the running instance's logs before changing anything about caching. If the first is new but the page still uses an old copy, the browser is holding a copy it was told it could keep.

  1. Look at Cache-Control in the response. max-age=3600, for example, tells the browser it may reuse the file for an hour without asking the server (MDN, Cache-Control, checked 2026-11-09). HTML is often served with a short lifetime or revalidated on every request, which is why the page can be new while its stylesheet is not.

The fix: make the URL change with the file

A browser can cache styles.css for an hour safely only if that URL's contents stay the same. Once the contents change, the URL must change too. Every produced file gets a version of its own:

<link rel="stylesheet" href="/styles.css?v=20261109-1">
<script src="/app.js?v=20261109-1" defer></script>

The version can be a build number, a short commit hash, or the file's modification time. The important rule: the marker changes when the file changes, and stays the same when it does not, so unchanged assets keep their long cache. Many build tools instead put a content hash in the file name (styles.9f2c1a.css); the effect is the same.

If the server renders the HTML, compute the version once at boot and use it in the template, so nobody has to remember to bump it:

const fs = require('fs');
const path = require('path');

const assetVersion = ['styles.css', 'app.js']
  .map((file) => fs.statSync(path.join('public', file)).mtimeMs)
  .reduce((a, b) => Math.max(a, b), 0);

// in the template:
// <link rel="stylesheet" href="/styles.css?v=${assetVersion}">

Then keep the HTML's own cache short — or revalidate it — so the next page load points at the new versions. The HTML is the index that says which CSS and JS belong to this deploy; a long-cached index pins visitors to an old, internally consistent set.

After a deploy, check from a clean cache

When it is not the cache

See also

Glossary terms used on this page: Container, Deploy, Host, Logs, Tool.

Sources

All checked on 2026-11-09.


First version written with AI assistance, from a deploy where the new HTML and the browser's old stylesheet combined into an overlapping page layout, and checked against the sources on 2026-11-09. Found a mistake? Fix it or open an issue. Text licensed under CC BY 4.0.