May 16, 2026
Two days lost to the wrong diagnosis
A build kept failing on the same line for eight iterations. The error pointed at a layer that wasn't the real problem.
For two days, a build kept failing on the same line. The error named a specific file that the file-watcher couldn’t read. Eight times we treated that as the truth: file-watcher bug, subtle config miss, poisoned cache. Eight different fixes. Eight times the same line came back.
The actual cause was upstream of the file-watcher and trivially diagnosable. A tool we’d installed a few days earlier had landed at the wrong version — the latest tag on the registry happened to be a future major bump that didn’t match the rest of our setup. The mismatch produced a duplicate sibling library in a nested directory; the dependency tree fragmented; the file-watcher choked on the fragmentation.
The standard health-check command for our toolchain prints this kind of mismatch in twenty seconds. We never ran it. For eight iterations.
The actual lesson
When something breaks in a place that’s been working, try the cheapest diagnostic first. Health-check commands, version-lock checks, “is everything where it should be” — these exist because people have hit exactly this class of mystery before and codified the answer. The reflex to skip them and dive into the layer the error names is what cost the two days.
The follow-on lesson
The error message was a perfectly accurate description of a symptom, and a misleading pointer to a cause. The file-watcher really wasn’t watching the file. The reason wasn’t its business; it was several layers upstream. Trust the error, but not the layer it points at.