Error messages
Things don’t always run smoothly. Our systems can fail. It’s important to craft clear, logical, and accessible error messages that help folks get things done.
Before writing anything, make sure you know the answers to these questions:
- What happened?
- How did it happen?
- How can it be fixed?
- Is it a user or system error, or both?
How can we expect a user to know what’s going on and how to fix something if we don’t?
A good error message structure explains what happened and what can be done about it. A good error message has the following structure:
Here’s an example of an inline form error message:
If we can’t place the specific error, we’re deliberately vague. The best we can do is tell the user how they might fix it.
We want to help folks fix errors quickly, so error messages should be concise. Strip out unnecessary words. Keep detail only when it’s relevant.
| Don’t | Do |
|---|---|
| “Can’t create ‘Engineering’ because a team with that name already exists. Specify a different name.” | “‘Engineering’ already exists. Try another team name.” |
| “Your notification failed and needs to be re-authorized.” | “Notification failed, please re-authorize it.” |
Apologize when it’s the system’s fault and let the user know it’s not their fault. Use an active voice to accept responsibility. For example:
| Don’t | Do |
|---|---|
| “Your changes couldn’t be saved.” | “We couldn’t save your changes.” |
Sometimes it’s the user’s fault, but there are ways to tell them without sounding like we’re pointing the finger. For example, we can focus on the desired action rather than telling the user they’ve messed up:
| Don’t | Do |
|---|---|
| “You’ve missed your name.” | “Please enter your name.” |
| “You can’t leave this blank.” | “Please enter a team name.” |
A passive voice can work for more serious user errors, such as “This card was declined”.
Tone is how you say something. A message’s tone should depend on how serious the error is. Warmth is great for less serious errors, but avoid anything too lighthearted for serious errors.
Avoid mechanical language and jargon, opting for plain language at all times. The aim is to make a user feel like you’re there, helping them solve the error.
| Don’t | Do |
|---|---|
| “The password entered does not match our records. Please re-enter your password.” | “That password’s not right. Try again.” |
At the same time, error messages are not the place to be clever or make jokes. This will only muddy your message and add to your user’s frustration.
| Don’t | Do |
|---|---|
| “Whoops! Looks like your card was declined. Better ask Mom for another one.” | “This card was declined. Try another payment method.” |
Some errors might need a button or link to fix or dismiss the message.
Always say what happens next. Buttons and links should make sense when read in isolation. Avoid just using things like “OK”. “OK” can be used to dismiss a message or take an action. Be clear to the user what they’re saying “OK” to.
| Don’t | Do |
|---|---|
Can’t display metricsYou need to restart your data sync. |
Can’t display metricsYou need to restart your data sync. |
Error messages should take the whole user experience into consideration. It should be clear what triggers an error message and what it’s related to.
- Inline validation styles are best for displaying errors in UI with form fields.
- Inline notifications are best for displaying errors in UI without form fields. They should be located within close proximity of items that affect a feature.
- Modals are best when you want to ensure you capture someone’s focus.
Toast notifications are best for confirming that an action someone performed is taking place or successfully completed. Since they appear away from the layout and disappear after a few seconds, toast notifications aren’t recommended for error messages.