How to Write Error Messages That Help People Fix the Problem
A good error message says what happened, where and how to fix it, without blaming the person. Rules from NN/g and Nielsen's heuristic 9, with examples.
Why do the words matter so much?
Because at the moment of an error the person is stuck. They want to finish something, and the system says it cannot. If the message is vague, they do not know what to change, and they tend to abandon or try things at random. Nielsen covers this in his heuristic about helping users recognize, diagnose, and recover from errors, which places messages at its core (NN/g: 10 Usability Heuristics).
That heuristic asks for plain language with no error codes, a precise description of the problem, and a constructive suggestion for a solution. All three matter, and a message that meets only one of them still fails.
What does NN/g say about writing them?
NN/g publishes a dedicated guide to error messages (NN/g: Error-Message Guidelines). Its most useful rules:
- Show errors close to their source, with visible and redundant indicators. Never use only color or only animation.
- Do not raise errors too early. Do not treat leaving an empty field as an error, but do offer real-time guidance for error-prone inputs such as passwords.
- Use plain language and avoid generic messages such as “An error occurred.”
- Offer remedies, not just the problem. Avoid blame words such as “invalid,” “illegal,” or “incorrect.”
- Preserve what the person typed, so they can correct it instead of starting again. Where possible, guess the fix and offer it as a choice.
- Avoid humor in errors.
NN/g reserves modal dialogs for severe errors. In most cases, the message should stay next to the field.
What steps does a good message follow?
Jakob Nielsen proposes five practical steps for the message (UX Tigers: Heuristic 9):
- Plain language.
- Diagnosis and direction: say what went wrong and where.
- An actionable solution.
- Visibility and tone: color and shape should draw attention without alarming unnecessarily.
- Recovery: a clear way forward, such as retrying, correcting, or getting help.
Nielsen gives a clear example: “Invalid input. Please try again” is a bad message, because it does not say what failed. “Your card was declined,” with possible causes, is better, because it informs and suggests what to check.
Examples: weak and strong
| Weak | Strong | Why it is better |
|---|---|---|
| Invalid input | Enter your postal code using five numbers | Says what is missing and how to fix it |
| An error occurred | We could not save your changes. Check your connection and try again | Explains the problem and the action |
| Invalid password | Your password must include at least one number | States the rule instead of blaming |
| Required field | Enter your last name | Concrete and actionable |
Notice that the strong versions do not use “please” or “sorry.” The GOV.UK Design System recommends avoiding both and writing the message with a direct action, such as “Enter your first name” (GOV.UK Design System: Error message).
How do color and tone fit together?
The sources do not fully agree. NN/g recommends conventional indicators such as bold, high-contrast red text and highlights, always with redundant indicators such as an icon. Nielsen, in his heuristic 9 article, prefers yellow warnings over red alerts in some cases. Both positions agree on the essentials: the error must be visible, and the person must understand what to do. Use the color your system already uses for errors, and back it with an icon and a sentence.
When should you NOT rely on an error message?
- When the problem can be prevented. If a date cannot be in the future, a calendar that does not allow an invalid date is better than a message that rejects it. NN/g and Nielsen’s error prevention heuristic both favor preventing errors before correcting them.
- When the error is not the person’s fault. If the service is down, the message should say so and offer an alternative, not ask the person to change something.
- When the message only makes sense to whoever wrote the code. Error codes can be kept for diagnostics, but should not be the main text shown.
To see when each field should be validated and avoid premature messages, read form validation timing. And for the difference between preventing and recovering from errors, see prevention vs. recovery from errors.
Illustrative example
Illustrative example: a medical appointment app shows “Error 422” when someone picks a time slot that is already taken. The team reviews session recordings and sees that most people choose the same slot again. The new message reads “That time is no longer available. These are the three closest times,” with three buttons and the rest of the schedule visible. The date field keeps the person’s choice. The error still happens, but now the person knows what to do in the next second.
If the error happens inside a form, also review form design. And for text that stays consistent with the rest of the app, the article on microcopy explains how to write the small words that guide people.
Common mistakes
- Showing “Something went wrong” without saying what, where, or what to do.
- Blaming the person with phrases such as “You entered the wrong data.”
- Clearing the entire form when there is an error.
- Using only color to mark the field with the error.
- Placing the error far from where the person is working, such as at the top of a long page.
- Writing a technical error message that nobody can interpret.
What you can do tomorrow
- Open your product, trigger three common errors, and copy exactly what each one shows.
- Rewrite each message with the formula: what happened, where, and what to do.
- Check that the text keeps what the person entered, and that the error is visible without relying on color.