Why Good Error Messages Are A Hidden Productivity Win
Most software ships with error messages that tell you something failed and nothing else. The teams that fix this quietly out-ship the ones that don't.
There's a quiet productivity gap between software that handles failure well and software that doesn't. The cost of bad error messages is invisible because it gets paid in help-desk tickets, Stack Overflow searches, and user frustration that never makes it back to the team that shipped them.
What makes an error message good?
Four things every clear error tells you.
A clear error message answers four questions:
- What failed? Specific, not 'an error occurred'. 'Could not connect to database server at db.internal:5432' is what good looks like.
- Why did it fail? The underlying cause in plain language. 'Connection refused' (network/firewall), 'authentication failed' (credentials), 'database does not exist' (config drift) are all different problems with different fixes.
- How do you fix it? Next action the user can take. 'Check that the database is running and accepting connections on port 5432' is a usable next step.
- Where to go for more? A doc link, support contact, or specific error code to look up when the obvious fix doesn't work. Bonus points if the code is grep-able in your own docs.
Most error messages get one or two of these right. Few get all four. The few that do are quietly the ones that lose less user time per failure.
Why are bad error messages so common?
The pressure that produces them.
Error messages get written in the worst conditions for writing anything good. You're inside the failing function, the test you're trying to pass is the happy path, the error message is what gets logged when 'something else' happens, and you have no idea who'll read it or when.
The result is overwhelmingly: bare exception strings, raw stack traces, language-localised generic strings ('Internal Server Error'), or - most common of all - a string that made sense to the original author and means nothing to anyone reading it three years later.
The fix isn't more discipline at the moment of writing. It's a habit at code-review time: 'is this error message useful to someone who doesn't have the codebase open?' One sentence of review feedback catches most of the cases.
How does AI-assisted coding change this?
Both easier and more important.
AI coding agents (Claude Code, Cursor, GitHub Copilot, etc.) make good error messages both easier and more important to insist on:
- Easier: Asking an AI to 'rewrite this error to follow the what/why/how/where pattern' produces useful output most of the time. Templates and house-style guides land more consistently when an agent can apply them.
- More important: AI-generated code is faster to ship, which means more error paths land in production per week. If those error paths all log 'Operation failed', you've just multiplied your help-desk load.
The teams getting this right tend to have a CLAUDE.md rule or equivalent that requires every new error message to follow a house style, then add quick review prompts when generated code doesn't comply. It's a 5-minute setup with compounding payoff.
Bottom line
Quiet craft, real returns.
Error messages are one of those parts of software craft that don't show up in marketing material or release notes but quietly determine whether your users keep using the product after their first failure. The teams that take them seriously aren't doing anything fancy - they're applying the four-question test consistently and treating bad messages as bugs worth fixing.
If your codebase has been growing at AI-assisted speed and you haven't audited error messages in the past quarter, that's where the next compounding productivity win is likely hiding. The investment is small; the user-time saved per shipped error is many multiples of the time to write it well.