A look into the right way to keep things running, both for software and automobiles.
If you’ve owned a car, you’ve likely seen it before, a glaring, yellow check engine light. Sometimes running into a 400 or 500 creates that same feeling: annoyance and inconvenience. It’s not a sure fire sign everything is broken but it likely means there will be a few hours lost in a liminal space, either at an auto repair shop, deep in the console logs, or aimless clicking to edit with the UI.
When your time at the auto repair shop comes to a close, you likely expect the person who worked on your car to give you a run down of what was exactly wrong with your car and not just an unspecified bill. Developers and users expect the same with error messages. Errors aren’t edge cases. They’re a moment when the user needs clarity the most.
Transmission : Some Examples
Bad message: A Warning Light
An error occurred.
Hopefully, a message like the one above is never encountered. This is like the service technician saying, “yep, your car isn’t working” and not suggesting a fix. It doesn’t provide a description of what happened nor an explanation why. It also leaves out potential fixes or links to runbooks with further information and context.
Better Message: A Diagnostic Code
Error 400: Invalid input.
This gives a better idea of what the exact error is and why, but it gives no nod to a solution. It’s more similar to a mechanic naming the specific part that’s having issues but still not giving a diagnosis for repair. Adding in further context of what specific input is invalid as well as why it is invalid would give a lot more direction to whoever is looking at this issue.
Best Message: Full Diagnostic Scan
Failed to parse configuration file ‘/etc/app/config.yaml’. The key ‘database.port’ must be an integer, but received string ‘three-thousand’. Follow /link/ to find this API’s inputs.
This gives the clearest picture into what is going on and an actionable next step, in this case updating the database.port key. It ties together the location, reasoning, and possible action plan.
Suspension: The Fix
Good error messages share the same ingredients as a solid mechanic’s diagnosis: location, cause, and a path forward. Here’s a starting framework:
“[What broke] because [why]. Try [action] or [fallback]. Still stuck? [link]”
Applied to the config example from earlier, that looks like:
“Failed to parse config.yaml because ‘database.port’ received a string instead of an integer. Update the value to a whole number and retry. Still stuck? See the configuration reference.”
A few principles to write by:
Be specific about location. “An error occurred” could be anywhere. Name the file, field, or endpoint so the developer or user isn’t hunting before they’ve even started debugging.
Separate the what from the why. What broke tells you where to look. Why it broke tells you what to fix. Both are necessary, one without the other is half a diagnosis.
Always offer a next step. Even if the fix isn’t obvious, a link to a runbook, relevant doc, or support channel costs nothing and saves significant time.
Write for the person at their most frustrated. Error messages are read under pressure. Short sentences, plain language, no jargon that isn’t already in context.
Alternator: More Alternate Examples
Cloud / SAAS Messages
Deployment failed because the environment variable API_KEY is missing. Add it under Settings → Environment, then redeploy. Still stuck? See the environment config guide /link/.
Fintech Messages
Identity verification failed because your name doesn’t match your government ID. Update your name under Account Settings and try again. Still stuck? Contact support with reference #48821.
AI / Design Tool Messages
Your prompt returned no results. Try using more specific language or reducing constraints. Tip: describing the action (‘resize and align’) works better than describing the outcome (‘make it look cleaner’)
Hardware / Telemetry Messages
Sensor stream paused — unit mismatch detected on channel 4. Expected m/s², received g-force. Update the unit mapping in your config and reconnect. View unit reference → /link/
Who’s the Mechanic Here?
In most error message pipelines, engineers write the code that throws the error, product decides what surfaces it, and technical writers find out when a user complains in a forum. Nobody dropped the ball, it just lives in the whitespace between job descriptions. The fix doesn’t require a reorg, it requires a single line of ownership: add an Error Copy section to your style guide, create a docs ticket template that fires whenever a new error code is introduced, and make error message review part of your API changelog process. A good repair place runs on a shared diagnostic codebook.
Final Thoughts
Errors are inevitable for even the best of engines. Leaving people stranded by them isn’t. What separates a good shop from a great one is what happens the moment the light comes on.
Error copy done well shows the users that the product team anticipated errors and prepared for moments of failure. It shows the developers a clear path on how to solve issues much faster — just like a good car mechanic guiding a driver from doom to vroom-vroom.
Top comments (0)