A Go service untouched for years is rebuilt on a modern toolchain and one test now fails: how do you triage it?

## Start from the right prior A service that has not been rebuilt for years and now fails one test after a toolchain jump is, overwhelmingly, a service that depended on something the Go 1 compatibility promise never covered. The promise binds the language specification and the documented standard-library API; everything else — unspecified behaviour, tool output, performance, and the correction of genuine bugs — was always free to move. Starting with "Go broke us" wastes the afternoon and usually ends in an embarrassing retraction, so start with "which unpromised thing did we lean on?" ## Read before you debug Each Go release ships notes with a compatibility section listing exactly this class of change. Read the notes for **every** version you skipped, not just the one you landed on, and read them against the specific symptom: one failing test is a narrow target and the notes are a short list. This is much faster than stepping through code, because the change you are hunting was documented deliberately. ## The four classes, and the different fix each needs **1. You asserted on unspecified behaviour.** A test comparing an error's message text, depending on map iteration order, on which ready `select` case fires, on goroutine interleaving, or on the order of equal elements from a non-stable sort. The fix is in the test: match errors with `errors.Is` or `errors.As`, sort before comparing, remove the ordering assumption. Nothing about the service is actually broken. **2. A bug fix exposed a latent bug in your code.** The promise explicitly allows fixing bugs in the compiler, runtime and libraries. Go 1.25 fixed a Go 1.21 compiler bug that had been delaying nil-pointer checks, which means some programs that appeared to work began panicking at a dereference they always contained. The fix is in your code, and the failing test just did you a favour. **3. A tool changed.** Tools were never in scope. `go test` runs vet analysers by default and gains more of them over time — as of Go 1.27 it runs the `stdversion` check — so a build can fail with no source change. `gofmt`'s output has changed, notably the doc-comment reformatting in Go 1.19, and that shows up as a CI diff rather than a test failure. The fix is to accept the tool's new output, or address the real issue it now reports. **4. A behaviour was tightened, often for security or correctness.** Standard-library packages do get stricter about malformed input. Here the fix is to stop producing or accepting the malformed thing. ## Bisect to name the change If the notes do not identify it, bisect. Install a handful of toolchain versions spanning the gap, run only the failing test with each, and narrow to the release where it flips. Then re-read that one release's notes; the change is almost always named there. Bisecting across releases is far cheaper than bisecting your own history, because your history did not change. ## Fix the dependency, do not freeze the toolchain Staying on the old toolchain is a legitimate way to buy a week, and nothing more. It costs you security fixes, it compounds — the next upgrade will have to cross an even larger gap with even more notes to read — and it leaves the actual defect in place. ## What to tell the architect The question behind the question is usually "is this language safe to build on for the next five years?" The honest answer is that the promise is narrow, written down and well honoured: upgrades are recompiles, and the failures that do occur cluster in a small, enumerable set of unpromised behaviours. The cost is a code standard rather than a migration budget — keyed struct literals, no assertions on error text or map order, CI that tolerates tool-output changes, and an upgrade cadence that never lets the gap grow to years. A team that pays that small tax rebuilds on a new toolchain in an afternoon; a team that skips it discovers all of it at once, exactly as this service just did.