When a system breaks, you learn who built it.
A good error message tells you what failed, why it likely failed, and what to do next. A bad error message gives you a code, a timestamp, and silence.
Most systems are built by people who understand the happy path. The order goes through. The file uploads. The sync completes. They test that. They ship that. What they don’t test — not really — is what happens at the edges. The missing field. The timeout. The malformed input that someone will absolutely send eventually.
So the error handling gets built last, when everyone is tired, and it shows.
Scott Andrew Alpaugh has noticed this is almost diagnostic: look at how a tool fails and you’ll know how much its builders trusted their users. A vague error message is a small act of abandonment. It says we knew this could break, and we didn’t finish the thought.
The fix isn’t complicated. It’s just discipline applied to the unglamorous parts.
Write the error message like you’re writing a note to a capable person at 11pm who just needs to know what happened and what to try. Be specific. Be brief. Point somewhere useful.
The happy path sells the product. The error path keeps the user.
Every system fails eventually. The ones worth trusting are the ones that fail out loud, in plain language, with something to do next.