Error messages

Error messages give users context about an inaccuracy, malfunction, unsuccessful action, or critical issue.

Published: March 14, 2023

On this page

Components

Form field

With the form field, users can create properly-styled controls in a form.

Alert

A brief message that provides information or instructs users to take a specific action.

Flashbar

Displays one or more page-level flash notifications to communicate the status of a user’s action, such as success, failed, and so on.

General guidelines

Do

  • Make it actionable. Help users understand what action they can take to resolve the problem.
  • While it’s important to be concise, when there’s information that can help users solve the error that has occurred, be descriptive to help users identify, troubleshoot, and resolve issues quickly.
  • If there’s a recommendation on how the error can be fixed, or technical details (such as error codes), include that information in the error message. If you’re unable to recommend an action in the error message, add a link for users to learn more.

Don't

  • Don’t display raw machine-generated errors as the primary message to users. Instead, write easy to understand and actionable messages for each error that your application might encounter.
  • Don't overwhelm users with error details. In alert or flashbar, you can place extra error details in an expandable section.
  • Don't make false promises to your users. For example, don't mention that your team has been informed about the error if you don't have an automatic tracking system for errors.

Criteria

Form fieldAlertFlashbar
Type of informationComponent specific directing users on what action to take. Component or page specific directing users towards next steps. Page or service specific suggesting next steps to users.
ContextPlaced below the related form field component that the error occurred in.Placed on the top of the page content or close to the specific element that the error occurred in. Placed on top of the current page user is on that may or may not be where the error originally occurred.
Action button-Might be needed to direct users towards next steps for error remediation. Might be needed to direct users towards next steps for error remediation.

Common error types

Validation

Follow the best practice guidance for what makes a good validation error message:

  • Avoid confusion:

    • Avoid implying user blame. For example: You didn’t enter a valid format.

    • Avoid jargon, and clearly define what went wrong.

  • Be consistent:

    • Use expected error message standards.

    • Use constraint text to define requirements and share format examples. Error messages should not be the first time users see requirements.

      • Example placeholder text: name@email.com

      • Example constraint text: Enter a valid email address. For example: name@email.com

  • Define problem and next steps:

    • Clearly define the problem. For example: Enter a valid subnet group name. The name has characters that aren’t valid: -

    • Use action verbs and define next steps. For example: Security code doesn’t match. Refresh the code and try again.

Alert and flashbar

Follow the best practice guidance for what makes a good alert and flashbar error message:

Writing guidelines

General writing guidelines

  • Use sentence case, but continue to capitalize proper nouns and brand names correctly in context.

  • Use end punctuation, except in headers and buttons. Don’t use exclamation points.

  • Use present-tense verbs and active voice.

  • Don't use please, thank you, ellipsis (...), ampersand (&), e.g., i.e., or etc. in writing.

  • Avoid directional language.

    • For example: use previous not above, use following not below.

  • Use device-independent language.

    • For example: use choose or select not click.

Component-specific guidelines

  • Use plain, everyday language rather than technical jargon. But, don’t oversimplify so that users can’t troubleshoot and resolve issues on their own.

  • Give users a clear action they can take to resolve the error.

  • Don’t use a tone that implies blame to the user.

  • Raw error messages do not need to be localized.

Validation errors

  • Follow the writing guidelines and UI strings for validation.

Alert and Flashbar errors

  • For error alerts, content should explain why the error happened if it’s known, and the action(s) the user should take to resolve it.

    • For unexpected client-side errors, use an expandable section to display the raw error message so that users can report additional information. Ask the user to contact you and provide this information.

    • Include specific details, such as number of errors (if applicable) and error codes or exception types if it will help users search for a solution.

  • Follow the writing guidelines for alert.

  • Follow the writing guidelines for flashbar.

Accessibility guidelines

General accessibility guidelines

  • Follow the guidelines on alternative text and Accessible Rich Internet Applications (ARIA) regions for each component.

  • Make sure to define ARIA labels aligned with the language context of your application.

  • Don't add unnecessary markup for roles and landmarks. Follow the guidelines for each component.

  • Provide keyboard functionality to all available content in a logical and predictable order. The flow of information should make sense.

Validation

Help users with error recovery by accurately identifying issues and providing easy identification of incorrect fields for correction.