Writing error messages: rules and examples

In short

An error message is where a product talks to the user at the most tense moment. They wanted to do something and it didn't work. The message's only job is to get them back on track.

This page is about the text of the message. When and where an error appears in a form is in the form design pattern. Here it's about what goes on that line.

I put the rules together from NN/g's 2023 error message guidelines and the error message component in the GOV.UK Design System. I wrote the examples myself.

What an error message should say

The ninth of Jakob Nielsen's 10 usability heuristics sums it up in one sentence. The message is written in plain language, contains no error code, shows the problem precisely and constructively suggests a solution.

I reduce it to two questions. Does the user understand what happened when they read it? Do they know what to do next? If either is missing, the message isn't doing its job.

GOV.UK distinguishes two ways of writing. An instruction tells the user what to do: “Enter your name”. A description states the rule: “Name must be 35 characters or fewer”.

In GOV.UK's examples an empty field gets an instruction and an input that is too long gets a description. You can use both, as long as you stay consistent.

Another GOV.UK suggestion helps: match the message to the label. If the label is “How many hours do you work a week?”, the message is “Enter how many hours you work a week”. When the user sees the same words twice, they immediately know which question the message belongs to.

Rules for error messages

Under each rule I wrote the source and the reason. The full references are at the end of the page.

1. Make the message visible. NN/g recommends showing errors in a bold, high-contrast, red style. Colour or animation shouldn't be the only signal, because many users find colours hard to tell apart.
2. Put the message at the source of the error, at the field. According to NN/g, proximity helps connect the message with the right field. GOV.UK shows the message in red after the question text and the hint.
3. Say exactly what happened. A generic sentence like “An error occurred” gives no context. NN/g asks for a short, precise description of the problem. GOV.UK also puts generic messages such as “This field is required” on its list of things to avoid.
4. Say how to fix it. Nielsen's ninth heuristic asks the message to constructively suggest a solution. Criterion 3.3.3 of WCAG 2.2 also requires showing a suggestion when the correction is known.
5. Don't blame the user. NN/g asks for a positive tone. Avoid words that imply the user did something wrong, such as “invalid”, “illegal” or “incorrect”. GOV.UK's list also includes “forgot”.
6. Don't write technical codes or internal terms. NN/g says to show error codes and abbreviations only when they help diagnose the problem. GOV.UK also lists technical phrases such as “form post error” among things to avoid.
7. No apologies, no “please”, no jokes. According to GOV.UK, “sorry” doesn't solve the problem, and “please” sounds as if the user has a choice. NN/g writes that a joke gets old fast for a recurring error.
8. Don't delete what the user wrote. NN/g asks you to preserve the input so the user corrects what they wrote instead of starting over. GOV.UK also says not to clear any field when showing an error.

GOV.UK's list of words to avoid includes “invalid”, “forgot”, “please”, “sorry” and “oops”. I treat it as the starting point for my own list.

Error message examples

Below, for the most common kinds of error, there is one bad and one good message. The good ones always follow the same pattern: the rule or instruction first, an example if needed.

• Empty field

  Bad This field is required.

  Good Enter your name.

• Wrong format

  Bad Invalid phone number.

  Good Enter a 10-digit phone number, for example (555) 123-4567.

• Too long

  Bad Character limit exceeded.

  Good Username can be at most 20 characters.

• Date in the past

  Bad Wrong date!

  Good The appointment must be after today.

• No choice made

  Bad Please select an option.

  Good Choose a shipping method.

• File

  Bad Upload failed (413).

  Good The file can be at most 10 MB. Choose a smaller file.

A note on the “for example” in the phone message. GOV.UK says not to repeat in the error message an example that is already in the hint text on screen. Only put the example in the message if the hint doesn't have it.

The voice belongs to the message too. Decide once how you address the user and keep it the same in every message. A form that is formal at the top and casual in the error reads as if two teams wrote it.

Exercise: rewrite a bad message

Each of the four cards breaks a rule. Write your own version and compare it with the suggestion. The tags show which rule is fixed.

Exercise: rewrite it

1 Email field

Bad Current version

Email

!Error: Invalid input.

anna.smith@gmail

Write your own first (optional)

Good Suggested version

Email

!Error: Something seems to be missing at the end of the email address. Enter it in the format [email protected].

anna.smith@gmail

• Fixed: Says what happened
• Fixed: Says how to fix it
• Fixed: No “invalid”

2 Date of birth field

Bad Current version

Date of birth

!Error: ERR_422: date_parse_failed

02/31/1990

Write your own first (optional)

Good Suggested version

Date of birth

!Error: Date of birth must be a real date. February has at most 29 days.

02/31/1990

• Fixed: No technical code
• Fixed: Plain English
• Fixed: Says what happened

3 Confirm password field

Bad Current version

Password (again)

!Error: Passwords don’t match! Please pay more attention.

••••••••

Write your own first (optional)

Good Suggested version

Password (again)

!Error: The two passwords aren’t the same. Enter the first password here again exactly as before.

••••••••

• Fixed: No blame
• Fixed: No “please” and no exclamation mark
• Fixed: Says how to fix it

4 Shipping address field

Bad Current version

Error: An error occurred.

Shipping address

Back entrance, 3rd floor left, ring the Miller family, leave the package ...

Write your own first (optional)

Good Suggested version

Shipping address

!Error: The address can be at most 200 characters. Right now it is 214.

Back entrance, 3rd floor left, ring the Miller family, leave the package ...

• Fixed: Sits at the field
• Fixed: Says what happened
• Fixed: Says how to fix it

Each card has a bad message of the kind I often see in real products. Write your own version in the field first, then press “Show suggestion”. The tags show what is fixed. I wrote the example messages for this page. With JavaScript off, both versions are open.

On the fourth card the real problem is where the message sits. A generic notice at the top of a long form hides the field with the problem. In the suggestion the message sits right above the field and gives the current character count.

User error or system error?

The examples so far were about the user's input. GOV.UK uses the error message component only for that. If there is a problem with the service itself, or a page isn't found, GOV.UK uses separate patterns.

GOV.UK also says not to use the error message to say “You're not allowed” or “You don't have access”. Those aren't input errors. They need a page that explains what the user can do.

NN/g also recommends choosing the form of the message by the impact of the error. For problems that need little interaction, a conditionally shown label, a short hint or a banner is enough. A modal demands attention and a resolution; keep it for serious errors.

When the server fails, the same two questions apply. Instead of “500 Internal Server Error”, write: “Your payment didn't go through, and your card wasn't charged. Try again in a few minutes.” At checkout, the first thing the user wants to know is what happened to their money.

My note

The error message I see most often in audits is “An error occurred”. That sentence is usually the default text development left in place. Nobody decided to write it.

That's why I keep error messages as their own list in the design file. For each field I list the possible errors and write one sentence for each. Development takes that list over, and no default text goes live.

GOV.UK suggests one more step: measure how often a message appears. That data helps improve content, run an A/B test or redesign the flow.

For a message that appears often, I think you first have to look at the question. Nielsen's fifth heuristic also says that even better than a good error message is careful design that prevents the problem in the first place.

GOV.UK also suggests a last test: read the message out loud. You wouldn't say “Invalid input” to a customer's face. Not on screen either.

A note on accessibility

Criterion 3.3.3 Error Suggestion in WCAG 2.2 is at level AA. If an error is detected automatically and a correction is known, the suggestion has to be shown to the user. The only exception: the suggestion would put the security or purpose of the content at risk.

The W3C explains the purpose of the criterion like this: only reporting the error can leave people with cognitive or visual disabilities without a solution. If they don't know how to fix the problem, they may give up on the form.

GOV.UK puts a hidden “Error:” prefix before the message. How I check a form from start to finish is in the guide to the accessibility audit, all criteria in the WCAG guide.

Checklist

I check a screen's error messages with this list before release. If you want me to review your product's messages, the UX Audit covers it.

• The message sits at the field with the problem.
• The error isn't shown only through colour, but also with text and an icon.
• The message says what happened.
• The message says how to fix it.
• No error code, no technical term.
• The words “invalid”, “forgot”, “please”, “sorry” and “oops” don't appear.
• The message uses the same words as the label.
• The voice is the same in all messages.
• After the error, what the user wrote is still there.
• The default text “An error occurred” no longer appears anywhere.