When something goes wrong, there are three crucial pieces of information error messages need to convey:

  1. What happened and what the consequences are.

  2. Why it happened and whether it will happen again.

  3. What needs to be done to move forward.

When crafting error messages, remember that most people scan text instead of reading. Make every word count and avoid extraneous details.

Here’s what you’ll find in this guide:

  • Best practices

    • Write for people, not machines

    • Use neutral and actionable language

    • Be empathetic, but not overly apologetic

    • Treat errors as opportunities

    • Keep text short and to the point

  • Voice and tone

  • Tips and tricks

Errors create high-stakes situations because it's frustrating when something goes wrong – especially when it involves work. Error messages give people the information they need to move on while also recognizing any frustration and soothing fears.

These best practices will help you balance those requirements and write error messages that convey crucial information about what went wrong with empathy and tact.

Try not to dehumanize the people who use your products. Avoid addressing people in the third person or using impersonal terms, like user, to describe them. Instead, speak directly to the people by using pronouns and contractions, and aim for a reassuring, conversational tone.

Do

Don't

When something bad happens, people tend to look for someone or something to blame. For that reason, it’s important to keep the language of error messages as neutral as possible. That means avoiding negative words or phrases, and focusing on next steps where possible. It also means it’s important to be cautious when using you and your, as emphasizing the relationship between the person and the problem could make them feel like they’re being chastised.

It can be hard to avoid you and your entirely. One way to do this is to use we instead. This is a way of taking responsibility for the problem.

Do

Don't

If taking the blame doesn’t make sense (for example, because the person reading the message really did do something wrong), try making the subject implicit by turning statements into instructions and moving pronouns out of the subject position.

Do

Don't

This can help soften the blow by identifying the person with the solution instead of the problem – empowering rather than blaming them.

Although it's counterintuitive, saying "sorry" in error messages can actually make the situation worse by causing errors to appear more severe than they actually are. Similarly, saying "please" can undermine the authority and credibility of your message and lead people to think a required step is optional. Unless the error has severe and irreparable consequences, avoid these kinds of niceties.

Do

Don't

While it’s important to be direct in error messages, it’s equally important to be helpful. Avoid messaging that focuses on the problem without offering a solution or way forward.

Treat errors as an opportunity to educate people. Help them understand why they’re experiencing an error and how they can avoid similar errors in the future. You may even be able to teach them something that can help them understand and manage the technology they use beyond your immediate product.

Do

Don't

By focusing on potential benefits, you may even find you can reframe an error as something else. Instead of focusing on the limitations of one type of experience, you can promote the benefits of another, as in the following example (shown when someone tries to access a particular kind of page using mobile web or an Android instant app).

Do

Don't

Helpfully reframing problems, as in these examples, can inspire trust and confidence in the people who use your products.

The longer an error message is, the harder it's going to be for people to find the information they need. Avoid padding error text with meaningless words, which may make it harder for someone to understand the core message.

So that error messages are easy to scan put critical details in titles, button labels, and the first four to five words of the body text.

Do

Don't

Error messages should be informative and encouraging, and they should provide a satisfactory resolution to a specific problem. Humor and wink can undermine the clarity of an error message and make someone who's experiencing a problem feel like we don't understand what they're going through. Plus, wink can be difficult to translate – what's funny in one language may not make sense in another.

That doesn't mean you can't have any fun with error messages, just that the copy might not be the right place for it. Here's a great example that uses visual humor to keep things practical, with a wink.

Do

Don't

The text and illustration in the example above were designed in tandem. The product team chose a common metaphor (construction work) that they used in both text and visual imagery, and the text is helpful and clear because:

  • there's a clear and concise header

  • the tone is friendly and reassuring, but not apologetic or winky

  • it uses progressive disclosure to point readers to additional information

It's pretty safe to assume that people who encounter errors are going to be frustrated, but how frustrated they are is going to depend on several factors.

Losing valuable work because of a computer glitch is going to upset someone more than a minor interruption to their workflow.

Error messages that draw attention to themselves might make someone more likely to remember when an error occurs, which could make them think it's happening more often than it really is, increasing frustration and eroding trust.

If someone can click a button to make an error go away and move on, they're less likely to perceive it as a serious issue.

The consequences of an error may be different depending on what the person who encounters it is doing. For example, a poor internet connection has different consequences for someone who's passively reading a page than it does for someone who's in the process of actively creating or collaborating on it.

When reading a page, a poor connection is a minor annoyance. The user:

  • can keep working

  • can't navigate to another page

  • won't get real-time updates

When you're editing a page, a poor connection is a major problem. You:

  • might not be able to keep working

  • won't know if your work’s been saved

  • might lose the work you've done so far

When crafting error messages, consider different conditions someone might be operating in when they encounter the error. Depending on what those conditions are, it may be appropriate to surface different messages depending on when, where, and how someone encounter an error.

If the error has more than one potential cause or solution, try one of the following UX writing strategies.

Use text, design elements, and visual clues to indicate minimums, maximums, limits, and other constraints before they become errors.

Stick to the most likely cause or the simplest solution the first two times, but if the error occurs a third time, provide another course of action (for example, contacting support).

For dead ends, start with something short but kind, and add context or other details only if the error recurs.