Writing helpful error messages

01What an error message must do

An error is the moment a user is stuck. The message has two jobs: explain what happened and show how to continue. Nielsen’s heuristic on helping users recognise, diagnose and recover from errors describes the same goal.

02Principles

Five habits cover most cases. Each one is easy to check in a review.

• Say what happened and how to fix it. Both parts, in that order.
• Use plain words. Avoid technical terms and internal jargon.
• Do not blame. Describe the problem, not the person.
• Be specific. Name the field and the rule that failed.
• Never show a code alone. A code can help support teams, but only after a readable message.

03Before and after

• Vague

  Before: ‘Invalid input.’ After: ‘Enter an email address like name@example.com.’

• Blaming

  Before: ‘You entered a wrong password.’ After: ‘That password does not match. Try again or reset it.’

• Code only

  Before: ‘Error 500.’ After: ‘Something went wrong on the server. Your changes are saved. Try again in a few minutes.’ (Use this only if the claim is true.)

04Placement, tone and accessibility

Good copy can be built from a short pattern: name the problem, give the reason if it helps, then give one clear next step. For example: ‘The file is too large. Files must be under 5 MB. Choose a smaller file.’

Where the message appears matters as much as what it says. A banner at the top of a long form leaves users searching for the problem field.

• Show the message next to the field it belongs to, not only at the top of the page.
• Keep what the user typed. Clearing a form after an error forces them to start again.
• Do not hide the message too quickly. A toast that vanishes in a few seconds is hard to read and impossible for some users to reach, so keep important errors on screen until they are fixed.
• Keep the tone calm and neutral. Avoid exclamation marks and humour at a moment of frustration.

Accessibility needs explicit work. Do not rely on red colour alone. Add text, and often an icon. Link the message to its field with <code>aria-describedby</code>, mark the field with <code>aria-invalid="true"</code>, and announce new errors to screen readers, for example with a live region or by moving focus to the first error.

WCAG 3.3.1 Error Identification (Level A) requires that errors are identified and described in text.

05Sources

• Nielsen Norman Group. 10 Usability Heuristics for User Interface Design. https://www.nngroup.com/articles/ten-usability-heuristics/
• W3C. Understanding SC 3.3.1: Error Identification. https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html