The rendering bug that took three weeks

It started, as these things do, with a screenshot in a Slack channel. A flicker. Half a second of empty layout before the dashboard painted. On most pages, you'd never notice. On the page that mattered — the one we used in every sales demo — it was the only thing you noticed.

I spent the first week looking in the wrong place entirely.

The wrong hypothesis

The flicker had all the surface marks of a hydration mismatch: brief flash, content shift, only on initial load. I added suppressHydrationWarning to a few suspects, audited every Date.now() in the tree, and convinced myself I'd found it three separate times. Each fix held in dev and reappeared in prod within hours.

What I didn't appreciate is that the flicker wasn't a render problem. It was a network problem wearing a render problem's clothes.

The actual cause

A dependency two layers deep was importing a 400KB polyfill it didn't need on modern browsers. The polyfill was synchronously evaluated on the client. The flicker was the gap between first paint and the polyfill finishing — React was perfectly happy; the browser was busy parsing.

I found it not by reading code but by opening the Network panel and sorting by transfer size. The villain was sitting there in plain text. I had stopped looking at the Network panel because I had decided, in week one, that this was a React problem.

What I took away

Three things, in order of how often I now repeat them to myself:

• Re-derive the symptom every Monday. If a bug has lasted a week, sit down and describe what you actually see — not what you think is happening. Half the time the new description disqualifies the current theory.
• Trust the tools you don't usually open. I'd looked at React DevTools fifty times. I hadn't looked at Network once. The bug was hiding behind the tool I'd dismissed.
• A "fix" that doesn't predict anything is a story, not a fix. If your patch works but you can't say why the old version was broken in a way that predicts other failures, you've moved the bug, not killed it.

Three weeks for a one-line change to a webpack config. Cheap, in the end.