What makes a good error message?

No one enjoys receiving errors messages, but software that fails silently or proceeds with the wrong assumptions is even worse.

Errors are encountered by real users with real goals. The error message is a communication method to help the user continue their goal.

3 questions for every error

  • WHY the program could not proceed?
    Context about the goal of the process being executed and why the situation is an error. If the error is due to user input or data from other systems, ensure to include it in the error message. Sometimes user doesn’t provide the input in the right format or the system picks or parses the wrong input. Announce your assumptions for the error.
  • HOW the error was detected?
    A map for finding the root cause and inspecting more. Stack trace, error code or even a state dump is very useful.
  • WHAT can be done to resolve it?
    Suggestions for recovering or taking an alternative path to the goal. If this is a typical error, mention one or more alternatives that can usually help solve the issue. If you have support channels make sure to include them as well.
  • WHERE did the error happen?
    This provides useful context information for the developers trying to trace and/or reproduce the error.
  • WHEN did the error happen?
    Usually a form of timestamp. This information can help correlate the error to failures in other systems while inspecting the root cause.
  • WHO was trying to achieve the goal?
    Usually some form of identification like user id, session id or even user name. This data might be subjected to GDPR regulation, see my other articles introducing GDPR and pseudonymization techniques.

--

--

--

Sr. Staff Engineer @volvocars, Knowledge Worker, MSc Systems Engineering, Tech Lead, Web Developer

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

Machine Learning Docker Template

Lua — Installation and LOVE2D

Resiliency and Chaos Engineering — Part 7

How can a non-programmer learn Python?

SOAR’n With DevOps(?)

Timing profiling code in Python

OPA Integration with Terraform

Jumping into Tech II: Where to land (Data Management)

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Alex Ewerlöf

Alex Ewerlöf

Sr. Staff Engineer @volvocars, Knowledge Worker, MSc Systems Engineering, Tech Lead, Web Developer

More from Medium

OOP - Differing Perspectives of the Interviewer and the Interviewee

What is an API exactly? A beginner’s guide to what an API is and how it works

Some thoughts on a Philosophy of Software Design

How Reusable Modules for Mobile Apps Cut Developer Time from 1 Week to 30 Min