Error messages

Handled with care, errors present an opportunity to strengthen our relationship with people who use our products. Consistent in-app support fosters trust and credibility.

    A well-designed error message

  • Reduces confusion by making a problem easy to understand.
  • Reassures people by providing a solution they can trust.
  • Eases frustration, which improves the experience.
Error message on a task management board, clearly describing an issue.

Do

Be specific and clear to ensure people understand what's happening.

Difficult and generic error message in an undefined place.

Don't

Avoid generic messages and technical jargon, which adds to confusion.

    Plan ahead

  • Consider what can go wrong early on. We might be able to prevent a broken experience.
  • Some errors are inevitable, but don't leave them as afterthoughts.
  • Make sure you understand the problem so you can explain it to others.
Text field showing character count within helper text.

Do

Keep people on the happy path with hints and clear helper text.

Text field not showing character count within helper text.

Don't

Even easy-to-fix errors are inconvenient and cause delays.

    Say it out loud

  • Write it the way you'd explain it to the customer—and never blame them.
  • Stay brief, on point, and use plain, everyday language to ensure clarity.
  • Provide a way out.
  • Don't use the word error, which states the obvious and doesn't add value.
    Exception: rare cases with detailed logs aimed at highly technical audiences.
  • Don't say oops, whoopsie, or use other cute language. It's redundant and annoying.
  • Don't use exclamation marks to avoid causing more stress.
  • Don't overuse sorry or please.
Concise and direct error message with a clear description of the issue and a solution.

Do

Communicating issues directly respects people's time and effort.

Consise and direct error message that assigns blame to the user.

Don't

Keeping it straightforward should never lead to assigning blame.

    Match tone to impact

  • Some errors are more challenging than others.
  • When the app encounters a technical issue, provide comfort and reassurance.
  • Use industry terms only if they're the easiest way to understand what's wrong.
  • Surround any specialized terminology with human words.
  • Don't use logs or error codes unless you know it helps the intended audience.
Easy to read error message that explains app failure, provides reassurance and provides access to error log.

Do

Taking responsibility for the problem shows honesty and builds trust.

Error message with no explanation or reassurance, showing error log without context.

Don't

Most people won't benefit from logs and codes without context.

    Anatomy of an error message

  • Identify 3 pieces of information: what happened, why it happened, and what to do next.
  • Decide if the context requires all that information and in what order.
  • For user errors, the most helpful could be a precise explanation of the problem.
  • For app failures, the user might benefit more from reassurance.
  • If you use a component with a title or heading, ensure it adds value.
  • Use the title or heading to say what happened. Skip the word error entirely.
4 examples of how error messages can be built using 3 interchangeable and combinable microcopy blocks.

Tip: think of [what happened], [why it happened], and [what to do] as building microcopy blocks. Choose the ones that match the problem's complexity and arrange them in the most user-friendly sequence.

    Inline error messages

  • Use them to help users fix slips and mistakes directly within input fields.
  • Stay brief since inline messages are highly contextual.
  • Provide an immediate explanation or a prompt on what to do.
  • Be specific by matching the error (“Enter your password”) with the label (“Password”).
  • Leave out please and sorry entirely. Those errors are easy to fix.
  • Avoid ambiguous valid and invalid. Instead, explain why the input can't be validated.
Inline error message showing how one of the microcopy blocks can be used in practice.

Do

Writing only [what to do] is often the most effective for inline messages.

Inline error message showing why another block might be a better choice, depending on the context.

Do

Using [why it happened] instead can sometimes be more direct and natural.

Share your feedback on the #design-systems channel in Slack.