How to write good error messages
We should always try to help users avoid error messages. But, things can always go wrong. Good error messages reassure the user and help them recover quickly.
A good error message can be the difference between success and failure. We should always try to
help users avoid errors, but things can always go wrong. Good error messages reassure the user and help them recover quickly.Write error messages in plain language, and aim for a reading age of grade 9 or lower.
Good error messages are:
- clear, written using plain language
- specific, explaining exactly what went wrong
- constructive, recommending actions the user can take to fix the problem
- neutral, focusing on the problem instead of blaming the user
Bad error messages are:
- complex, written using technical language
- vague, not providing enough detail
- unhelpful, leaving the user to figure it out on their own
- accusatory, implying it’s the users fault
Tone of voice
The tone you use is important. It should be calm, clear, and helpful. It should not blame the user.
To get the tone right, use these 5 principles:
1. Be concise
Be brief, but informative. Many users won’t read more than the first line.
Do not use terms like:
- oops or uh-oh, because errors aren’t funny
- please, because it implies a choice
- something went wrong, because it’s too vague
Good examples:
- We could not save your dashboard
- We could not load your data
- We could not install the AWS integration
Bad examples:
- Uh-oh, the AWS integration failed to install
- Please check your configuration for invalid entries
- The request could not be completed, malformed syntax
2. Be clear
Use plain language. Avoid ambiguity. Tell the user exactly what went wrong.
Do not use terms like:
- forbidden, illegal or prohibited, because they sound scary
- you forgot, because you don’t know if they did
- valid and invalid, because they aren’t specific
Good examples:
- Enter your date of birth in the format dd mm yyyy
- Your password must be at least 8 characters long
- Your email must contain an ‘@’ character
Bad examples:
- Syntax error
- Invalid input
- Request failed
3. Be reassuring
Don’t blame the user. Reassure them by giving them actions they can take to try and fix the error.
Do not use terms like:
- You did not [complete a thing].
- You failed to [do a thing].
- Because you [did something wrong].
Good examples:
- You can try again.
- You can contact your administrator.
- You can read the documentation.
Bad examples:
- You forgot to enter your API key
- You failed to fill in your email address
- Because you selected more than one option
4. Be sincere
‘Sorry’ gets overused. You’re not really sorry the user mistyped their email address, so saying it sounds insincere. It also does not help them fix the problem.
Avoid saying sorry. Unless it’s an application error or a service outage that is definitely our fault, then it might be acceptable.
Good example:
Sorry, Elastic Cloud is down. Our team is working hard to restore it. Check our status page for real-time updates.
Bad example:
Sorry, you didn’t enter an email address. Please enter your email to continue.
5. Be active
Use the ‘active voice' wherever possible, as it makes responsibilities clear. The passive voice makes it difficult to work out who was at fault and who needs to take action.
Address the user as ‘you’, and address Elastic as ‘we’, and be clear who needs to do what.
Good example:
We could not save your dashboard
Our cloud service is currently unavailable. This is probably a temporary issue. Wait for 1 minute and try again. If this keeps happening, contact your administrator: admin@example.co
Bad example:
Sorry, data not saved
Your data could not be saved, client error 503. Try again later.
Structure
A good error message can be broken down into 3 parts:
- the problem
- the cause
- the recommendation
1. The problem
A clear, short description of what went wrong. It should be informative but scannable. Remember, many users will not read more than the first line.
Do not be overly specific when describing the problem. You don’t need to include variable names or error codes at this level.
When writing about the problem, you should be:
- concise, explain the problem in as few words as possible
- clear, use plain language and explain exactly what went wrong
- sincere, do not use the word sorry unless it’s definitely our fault
- active, write in the ‘active voice’
Good example:
We could not save your dashboard
Bad example:
Sorry, data not saved
2. The cause
The cause is additional information which can add more context to the error. It might not always be needed, do not just repeat the problem.
If you need to, you can include error codes at this level, but they should only be included if they are genuinely useful to the user.
When writing about the cause, you should: decide if it’s needed, the problem might be self explanatory elaborate on the problem, including more specific details that might be useful include error codes, if they are useful to debug the problem avoid repeating yourself
Good example:
Our cloud service is currently unavailable.
Bad example:
Gateway timeout 504.
3. The recommendation
If the user can fix the problem themselves, tell them how to. If they can’t, tell them who to contact to fix it for them.
When writing the recommendation, you should be: reassuring, set expectations, tell them if it’s likely a temporary problem informative, tell the user things they can try to fix it themselves helpful, tell the user who they can contact or what documentation they can read
Good example:
This is probably a temporary issue. Wait for 1 minute and try again. If this keeps happening, contact your administrator: admin@example.co.
Bad example:
Try again later.