Part 5: The Upgrade That Didn't Happen

Around September 11, I set out to upgrade Sanity Studio, my content editing screen, to its new major version, 6. Staying current seemed like good housekeeping. At first it looked easy. My settings files were clean, I used only Sanity's official add-ons, and my computer's Node.js version was well above the minimum.

Then Studio refused to load, with an error saying a component called Activity couldn't be found and React needed upgrading. React is the toolkit the site's pages are built with.

A methodical hunt

What followed was a long, careful process of elimination. We tested one theory after another: the tool that bundles the code, an outdated Sanity add-on (which we did upgrade), conflicts between package versions, duplicate copies of a design library, a leftover page setting, a handful of configuration options, and whether two copies of React were installed. Each theory was checked by looking at the actual files on disk, not by guessing from what the package lists claimed.

The answer finally came from reading the compiled code directly. Next.js quietly swaps every request for React, including the ones deep inside Sanity, over to its own built-in copy. The copy shipped with my version of Next.js simply doesn't include Activity. A search of that file came back empty. Sanity Studio 6 needs Next.js 16, and no update to my current version would fix it.

Parking it properly

So we stopped. All the upgrade work was saved on a separate git branch named sanity-v6-upgrade, with a note saying it was in progress and required Next.js 16. A branch is a parallel copy of the project where you can experiment without touching the main version. The live site stayed exactly as it was, and the Next.js 16 upgrade became its own future project.

It's tempting to see a session like this as wasted. It wasn't. I came out with a definite answer, a clean main branch and a saved head start for when the time comes. Abandoning the effort halfway, with half-upgraded packages on the live branch, would have been far worse.

The lesson

Test each theory against the actual evidence, one at a time. And knowing when to stop is a skill. When the answer is "not yet," park the work on a branch and keep the main version clean.

Try it yourself

Before any big upgrade, ask the AI to create a new branch first. If the debugging starts going in circles, ask it: "What would prove or disprove this theory?" That one question keeps a long session honest.

Next time: invisible headings, and how the parked upgrade came back to bite.