Writing for errors

Avoid showing a message whenever possible

The best error message is no error happening at all. The message — and the error itself — are disruptive to a user’s experience and can stand in the way of them accomplishing their task. Make sure that the system can anticipate and address errors on the back end before showing an error message on the front end.

Find ways to avoid the error altogether, like by using in-line validation, visual cues, and disabled states to guide users. Ensure your design is as inclusive as possible by anticipating and accommodating multiple spellings of words in search queries and results.

Have the system automatically resolve errors

Error messaging should be a last resort. Try whenever possible to design experiences in a way that the UI doesn’t rely on showing error messages or prompting direct user action to resolve an error.

For example, if a user were to input “101” when a field can only accept numbers up to 100 (such as showing percentages), automatically revert the entered value to 100.

Choose the message first, then the component

Error messages appear in the wrong UI components all too often. A complex message is usually too long and too complicated for a toast, and a short and straightforward message is far too much for an alert dialog. Errors that are lower in signal or consequence shouldn’t warrant a dialog that blocks the entire experience, and errors that are high priority shouldn’t appear in a toast with a timeout of only a few seconds.

Write out what the message should say, free of any UI constraints, to understand how you should say it. Then, determine the right component for the message. Learn which component to use, when.

What happened

This should be the first part of the message, like in a headline (if the UI element allows). Be sure to communicate the general outcome of the error. Use plain language and focus on what it means to the user.

The underlying cause

It’s helpful to have an explanation of why something happened, if there’s space to include it. Explaining the cause is optional depending on the context; sometimes this can increase a user’s understanding, but sometimes it gets in the way of useful, usable information.

How to fix it

This part tells the user what they can do about it. If there’s nothing for them to do, then explain what the product is doing. This should be as simple and actionable as possible. Offer a path forward within the error state itself, such as a “Try again” or “Go back” button, or a step-by-step resolution in the error message text.

Linking to a help article can be useful, but only if that article is specific and descriptive to the error’s use case. Try to avoid generic, catch-all resolutions like “Contact your IT administrator for details.”

Center the language around user goals, not system constraints

Sometimes it seems like the best way to resolve an error is to explain the constraints of the system to the user. But, most users don’t care about the constraints of the system — they care about accomplishing their goals.

Center the language around what the user is trying to accomplish, why that didn’t happen, and how they might resolve the error.

Use plain language, and avoid jargon

Users may not understand server architecture or client-side queries. Know your audience, and write your error messages in plain, usable language so that your user will understand what went wrong and how it’s being resolved.

Technical terms are different than jargon. If you’re confident that your audience would be readily familiar with technical terms, and if such terms are relevant to the message, you can include them.

Don’t blame the user, even if the error is their fault

Some errors are outside of a user’s control, but they can happen because of a direct user action. While you want to tell a user what happened, don’t sound accusatory or that you’re blaming them — we want them to feel supported and taken care of in any experience.

Include error codes only if useful and relevant

Again, think about your audience. Include an error code or other technical information if your users would benefit from having it in order to resolve the error.

Put error codes at the end of the message so that readers aren’t potentially overwhelmed with information they may not understand at the start.

Use positive framing to keep the focus on what users can do

While a user will want to know what went wrong, be as clear as possible about what they can do to fix the error, or provide them with an alternative workaround. Sometimes it’s simple (“try again in a few minutes”) and sometimes the only solution can be time-intensive or potentially frustrating (“contact your IT administrator”).

Avoid putting the focus on the problem, what a user can’t do, or what they did incorrectly. Instead, offer context and help people understand what they can do.

Create error states that are specific to each case whenever possible

It may be tempting to write a catch-all error message to accommodate dozens of similar scenarios, but that will tend to be wordier and less concise. When users need to understand multiple causes of the error — and also figure out which one applies in their scenario — that creates a lot of unnecessary cognitive load in an experience.

Creating multiple, more specific error messages takes additional effort, but it ultimately creates a better user experience. Having these can also provide clearer insights and analytics that can help identify and resolve common pain points — and show you how to prevent errors from happening in your product in the first place.

While the error should be specific, use generic language

Generic language allows for better localization, and it also reduces the need to write many different versions of messages for similar use cases. It’s usually unnecessary to include specific filenames, usernames, or folders because a user can get that context from elsewhere in the UI.

Don’t apologize unless it’s warranted

Apologizing for minor mistakes or when the system is not at fault sounds insincere, and it gets in the way of the important parts of a message.

Save “sorry” for serious errors: when there’s data loss or something requires a user to take a major action to resolve the issue.

Use passive voice sparingly

Try to write in active voice, which is quicker and easier to parse. Passive voice is useful to soften a message that might otherwise come across as blunt or terse, especially when the error was caused through user action or inaction.

Own mistakes, and help users parse complicated actions with “we” and “you”

We typically avoid referring to ourselves — meaning “we,” the interface — in UI copy because it adds unnecessary cognitive load. But, directly referring to the interface as "we" and to the user as "you" in an error message can be a clear and helpful way to answer the questions "where did this go wrong?" and "who needs to take action to fix it?"