5 things to remember when writing a good error message

February 3, 2022

5 things to remember when writing a good error message

Regretfully, error messages are a part of our craft. And after asking around, there seem to be few developers out there who know how to write a good error message as evidenced by the error’d section of thedailywtf.

Although error messages are part of the UX, it’s not the UX designer’s responsibility to write one that’s appropriate for the app. And since hiring a copywriter for these messages isn’t realistic for smaller teams, this means that this is often done by the developer that wrote the code.

Error messages are all about informing the user - and they are not necessarily caused by bugs in the code.

A developer cannot help it when the internet connection does not work, or when a firewall is blocking the port that the application intends to use. A developer cannot also help that hardware might fail and therefore cannot connect to your smartphone. They also cannot help that a power outage broke some sectors on your hard drive.

Simply said, the developer cannot control the possible reasons why something would not work. However, the developer can help the user out by writing a good error message.

Let’s look at this example:

Unable to print the document because the application is unable to connect to the printer. Ensure that the printer is connected on both ends and that the printer switched on, and try to print again. If the problem persists please contact support.

When structuring your error message, it’s important to consider the following questions:

  • What happened and why?
  • How does this affect the user?
  • What can the user do to avoid this from happening again?

By keeping these questions in mind, you address the issue encountered by your user, acknowledge how it impacts their experience; and finally, opens an opportunity for next steps.

Now that we’ve covered that, here are some guidelines to help you write your error messages:

1. Avoid error messages.

Good design, micro-interactions and common sense could prevent the user from seeing the error message altogether. In the example above, we can avoid the user clicking on the print button by disabling it and show that no printer is found. A tooltip can reveal the same instructions as the error message.

2. Avoid technical jargon.

The only thing the developer is interested in is stack traces and exception types and should end up on your to-do list through proper instrumentation.

3. Consider how you deliver the message.

Only respond with error messages to direct user interactions. Consider getting an alert window popping up in your face while an error is caused in some background process that you as a user are not even aware of!

4. Use simple and complete sentences.

Avoid using negative words, the word please, exclamation points, uppercase text, abbreviations and acronyms.

5. Humor is good - but only when it applies.

A recent movement we’ve observed includes humor. And while this might be great for a 404, if the user is unable to save his hard work, your big embarrassed smiley face may not get the response you were aiming for.

Stick with something appropriate that also speaks to what your users would feel when they encounter an error.

Overall, if you have to write an error message, aim for one that’s straight to the point and easy to understand.

This lessens the negative impact of the error that occurred. People will be more understanding of what happened and open to solutions provided.

Our mission is to delight countless users with beautiful, easy to use, well-architected and highly maintainable SaaS made to scale. We’ve also co-created numerous SaaS products with clients at varying stages, deadlines and budgets. Learn more about what we do and how we can bring your idea to life.

saas venture partners company profile