The homepage “What I build” grid has six category cards. Each card has an icon. On 30 October I checked the homepage on my phone and every icon sat in a pale box, a near-white fill cutting against the dark card background. The files under public/icons/categories/ were Gemini renders from June, produced when the section first shipped: wrong background style, wrong era, generated by a tool I’d already retired.
Four days earlier I’d deleted the Gemini image harness from the codebase: scripts/image-harness/ and its two legacy wrappers, gone. ChatGPT had replaced it as the image generator. The six category icons were a natural carry-forward from that decision: rerun them in ChatGPT, file the outputs at the same paths, close the pale-box problem alongside the harness migration.
I ran all six, picked the results, filed them into public/icons/categories/, opened PR #566.
The merge that changed nothing
PR #566 merged. Deploy completed. I opened the live site on my phone.
June icons. All six. Still in pale boxes.
The first assumption was a stale or failed deploy. That was wrong. The deploy logs were clean. I checked the actual bytes: md5 over HTTP, comparing what the host served against what the repo held. The new files were on the server. Byte-identical. Whatever had gone wrong, it was not the server.
The browser was not serving the new files.
What cPanel does by default with static paths
The host serves everything under /icons/ with cPanel’s default Cache-Control configuration: public, maximum age of one year, immutable.
The max-age alone would mean browsers revalidate after a year. The immutable directive goes further. It tells the browser the resource at this URL will not change during the cache period, so there is no need to issue a conditional GET, no need to send If-None-Match, no need to check the server at all. The cached copy is treated as permanently correct until the timestamp expires.
Each URL under /icons/categories/ had been fetched and cached in June. As far as every browser that had visited the site was concerned, those URLs would stay valid until June 2027. Replacing the bytes at the same paths changed what new visitors received. It did nothing for anyone who had the URLs in cache. The server and client could hold genuinely different files under the same paths for up to a year, simultaneously, with no error surfacing anywhere in the delivery chain.
This is not a misconfiguration. The header says exactly what happens; I hadn’t read it.
The fix
URL versioning. If a resource at a given path is cached indefinitely, change the path.
The category icons moved to versioned filenames. Every browser fetches a URL it has never seen, so there is no cached copy to serve. No CDN purge, no cache invalidation endpoint, no conditional request logic. The browser simply has no entry for the new URL. Clean fetch, correct file.
The old un-versioned paths stay in cache for the rest of their window. That’s fine: nothing links to them any more. They expire quietly.
The overhead is clear. Manual versioning means any future update to these icons requires another path change. Forget the step and the same problem recurs. Six icons that change infrequently is a manageable commitment; automated content-addressed filenames at build time would eliminate the manual step entirely, but that requires changing the static export pipeline. That’s a separate sprint.
Out of scope: switching icon delivery to next/image or a build-time content-hash scheme. This site uses a static export with next/image disabled for icons, and the infrastructure change required to swap that out is larger than the problem it would fix today.
The rule this makes concrete
Image work has two distinct parts. Making the image is the first; getting it to the client is the second.
For any asset served under an immutable or long-lived cache directive, the second part requires a URL change. Checking the server has the new file is necessary but not sufficient. The same goes for a clean deploy and for byte-identical HTTP responses. Until the URL changes, returning clients see whatever they cached on first fetch.
The failure is silent. The deploy pipeline reports no error, the server returns no HTTP error, and the browser console stays clean. The client serves a stale file from cache and reports 200 OK against the original URL. Every automated signal reads as success.
The phone as a verification layer
Most of my checks were on a development machine in Chrome. Chrome wasn’t showing June icons: I’d hard-refreshed at some point, and the cache for this origin was cold. The phone, running Safari on iOS with full browser cache intact from previous visits and no dev tools, showed what a returning visitor actually sees.
The development machine is a poor signal for cache-sensitive changes. Any browser that has recently hard-refreshed, or was launched in an incognito window, has a cold cache. That is not representative. For any change to a static asset under long-lived headers, the accurate verification is a device that has not recently cleared its cache for this origin. The phone caught this; the deploy pipeline didn’t, and cannot. It verifies server state, not what the client has stored.
Worth building into the process, not treating as a lucky catch.
What I’d tell past-me
Before replacing a file at an existing path, check the Cache-Control directive governing that path. /icons/, /fonts/, /static/, any directory a host treats as permanently cacheable, requires versioned URLs for changes to reach returning clients.
The md5 check was the right move. It ruled out the server as the failure point and pointed directly at the client layer. “The server has the correct file” and “the client sees the correct file” are two claims, not one. The md5 check answered the first. The pale boxes on the phone answered the second.
The June icons were a commitment I didn’t know I’d made. An un-versioned path under an immutable directive is a promise to every client that fetched it: this URL will not change. Replace the file without changing the URL and the promise holds for the server. The client doesn’t find out until the cache expires, or until the URL changes first.