What makes a good error message?

No one enjoys receiving errors messages when working with computers, but there is something worse: software that fails silently. Can it get even worse? Yes: software that proceeds with the wrong data or assumption.

But let’s stay positive: if errors are not all that bad, what are the characteristics of good errors?

3 questions for every error

A good error is actually very helpful and can potentially prevent disastrous and expensive consequences. An error message is a communication medium and as beautifully elaborated by this TED talk, it should start with why.

A good error message should indicate:

• WHY it went wrong and the computer can’t proceed? Context about the goal of the process being executed and why it is an 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
• WHAT can be done to resolve it? Suggestions for recovering or taking an alternative path to the goal.

Error consumer

If the error is supposed to be consumed by someone other than the end user (support, developers, auditors), there’s typically an online or offline logging system in place.

• An offline log: gathers the information on the user’s system without transmitting it to the consumers . The most common forms of offline logs are memory dump, stack traces or log files. In this case the user is offered with choices for how to transmit the error (usually an optional step).
• An online log: gathers the information on a remote server. All you need to give to the user is a unique id that can be used to put together an error report for what they were doing.

In this case the error should also answer:

• WHAT does the end user need to do?Steps to send the unique error id or offline log for further investigation and support
• WHEN did the error happen?Usually in form of timestamps
• WHO was trying to achieve the goal?Usually some form of identification like user id, session id or even name. This data might be subjected to GDPR regulation, see my other article on the matter:

• GDPR terminology in plain English
• GDPR pseudonymization techniques

Examples of bad errors

Too many systems fail to give a good error which leads to user frustration. Windows Blue Screen of Death (even has its own acronym BSOD) is probably one of the most cursed error messages:

For an operating system that is developed for non-technical end users, it has embarrassingly too little information. It fails to answer WHY, briefly touches briefly on WHAT and jumps to WHERE the error happened. The instruction for HOW to solve the error is generic and not very specific (because the WHY is often unknown).

2 decades later, Windows shows even less information and expects the user to pull out their phone and scan a QR code:

Examples of good errors

The web platform is much more flexible and leaves room for creativity with powerful tools.

404 (page not found) is a classic error on the browsers. While some sites just throw the error number at the user and expect them to figure out the rest, Hootsuit has an actionable button: go to the main page:

Can it be done better? Of course. List24 don’t leave you there, it suggests you to search and even offers you some alternative content to click on right away:

While some like Path show empathy:

Chrome totally distracts the users by offering them a game when it can’t connect to the internet:

Conclusion

Software developers usually treat the errors as the ugly part of their code. That is because they are mostly aiming for the happy scenario where everything works and they solve the problem that the software has promised. However, when the end user is trying the software, they experience the real scenario which is different from the happy scenario in many ways:

• WHAT? They use real data for real activities (as opposed to test data and activities)
• HOW? When they fail, they feel more frustrated because they don’t have the source code ready to be tweaked and fix the problem
• WHY? They often don’t have enough context for what went wrong (hence the cliche of cursing the “computers”)

Good software is a pleasure to use. It not only prevents errors, but when it fails, it gives actionable error messages that help the user understand why it went wrong, how the error was detected and what can be done to solve it.

If there’s one key take away from this article, I want it to be:

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

⚡️Liked what you read? Follow me to be notified when I write something new.

What makes a good error message? was originally published in Hacker Noon on Medium, where people are continuing the conversation by highlighting and responding to this story.