Error messages
Error messages inform users of an error, malfunction, unsuccessful action, or critical issue. The error message gives a description of the issue, and provides next steps to fix it.
On this page
Did this page help you?
Tell us more - optional
Components
Form field
Alert
Flashbar
Key UX concepts
Make it actionable
Help users understand what action they can take to resolve the problem. Make this action the main point of the message. If you're unable to recommend an action in the error message, add a link for users to learn more.
Provide relevant information
While it’s important to be concise, provide all relevant information in error messages. 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 or exceptions types that users can search online), include that information in the error message.
Don't blame the user
Keep the message neutral, focusing on helping the user fix the problem. Avoid using negative words or implying blame, for example, “You didn’t enter a valid input.”
Contextualize errors
Error messages can be standalone field errors resulting from validation or be more complex requiring users take action on multiple elements across pages. In either case, provide error messages to users in the context of where the error occurred when possible, accounting for the scale and criticality of these errors. Example:
Show inline field error message for standalone field errors resulting from client side validation.
Show a page level error alert above the submit button for an error resulting from server side validation.
Show a page level flashbar for an error returned due to failure in deleting a resource.
Show an error alert where a component failed to render.
General guidelines
Do
- Use the built-in component error states for component specific functional errors whenever applicable, instead of creating new ones.
- For field and form validation, follow the pattern recommendations outlines in the validation pattern.
Don't
- Don’t use error messages to display warnings. Error messages imply critical failure which needs immediate user attention and often requires rapid user action to continue with the flow. Warnings on the other hand are advisory.
- 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. 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 field | Alert | Flashbar | |
---|---|---|---|
Type of information | Component 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 |
Context | Placed 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 maynot 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
Form or field validation
Client or server side errors that occur as a result of validation on a form, field or flow. They usually require a user to perform an action on that field, form or another page to remediate the error. Refer to the validation pattern for details on scenarios and guidelines on addressing them.
Network
Errors resulting from network failures such as issues fetching data or trouble retrieving a page. The remediation for these issues is usually trying to load the data again.
Component specific functional errors
Errors that occur in a component due to fetching or loading issues. For example:
The autosuggest has a built-in error state which is displayed when an error occurs while getting suggestions based on the user's entered query.
The multiselect component error state occurs when it fails at fetching options (for example, if the API fails to load the next set of options in the list).
The code editor error state is displayed when the component fails to load.
The individual charts components have an error state which is displayed when they fail to fetch data.
Unexpected client-side errors
Errors that occur due to a technical malfunction. For example, when a component fails to render. The cause of these errors is usually unknown, and there might not be a clear action to fix it. Instead, users can report the problem, and then reload the page or retry the operation again later.
Features
Flashbar and alert
Follow the respective guidance for flashbar and alert.
- Failed to delete instance id-4890f83eThis instance is still running. Stop the instance and try deleting again.
Reload the page or try again later. Contact us and share more details.
Header - optional
Error message headers should describe what the error is in an informative, scannable way. Headers should be limited to no more than 4 words, use sentence case, and avoid using terminal punctuation. If the message is one sentence, a header is not necessary. For example, “Your instances could not be stopped.”
Description
Descriptions should explain why the error happened if it’s known, and the action(s) the user should take to resolve it. Add links to any additional documentation users can read to learn more if needed. Also 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. Keep descriptions concise, 1-2 sentences, and use terminal punctuation at the end of each sentence. For example, “Remove the instance from the load balancer before stopping 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.
Action button - optional
Action buttons should clearly describe the steps needed to resolve the error. Use an action verb (“Retry”) or an action verb plus noun (“Restart instance”). Action buttons should be 1-2 words and should not include terminal punctuation. In instances where there is no clear action that the user can take, don’t include an action button, but instead add a link to learn more.
Form field
Error text
Error texts in form fields should let the user know what is causing the error. If the error is about unmet requirements mentioned in the constraint text, don't repeat the same information. Instead, let the user know that there are unmet requirements. For example: The name has too many characters. Character count: 120/50
For format not valid error messages, use the format: Enter a valid [label descriptor] [label type]. For example: Enter a valid email address.
If a user neglects to fill in a required field on a console page, use the format: [label descriptor] [label type] is required. For example: Alarm name is required.
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 interact 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.
Form field label
Follow the writing guidelines for form field.
Form field description
Follow the writing guidelines for form field.
Form field error messages
Required field:
Use the format: [label descriptor] [label type] is required.
For example:
Alarm name is required.
Template URL is required.
Expiration date is required.
Custom engine version description is required.
Format not valid:
Use the format: Enter a valid [label descriptor] [label type].
For example:
Enter a valid email address.
Enter a valid subnet group name.
Enter a valid phone number.
Enter a valid KMS key ARN.
Doesn’t match:
Using one short sentence, indicate what doesn't match.
For example: The security code doesn’t match.
If additional context is necessary, follow the first sentence with clearly defined next steps.
For example: The security code doesn’t match. Refresh the code and try again.
Character requirements:
Use the constraint text area to include any character count requirements needed to validate a form field, rather than using validation error messaging. When triggered, the corresponding validation error should let the user know which constraint text requirements are unmet.
For example:
The name has characters that aren’t valid: #
The name has too many characters. Character count: 120/50
The name has too few characters. Character count: 1/50
Form field constraint text
Keep constraint text brief. Two lines is the limit.
Use regular text, not italics or boldface.
Value constraints:
If there are constraints on the value that users enter into an input field, describe them under the field. Use the format: [label descriptor] [label type] must be X to Y characters. or [label descriptor] [label type] must be X to Y characters, and must/can't [constraints].
For example:
Category name must be 1 to 100 characters.
Category name must be 1 to 100 characters, and must start with a letter.
Category name must be 1 to 100 characters, and can’t start with a hyphen (-).
When sharing valid characters, use the format: periods (.) instead of (periods) “.” and use the format: Valid characters are [valid character list].
For example: Valid characters are a-z, A-Z, 0-9, and periods (.).
Valid formats:
If there is a valid format users must provide (for example, an email address or phone number), share an example within the constraint text rather than (or in addition to) inside placeholder text, which is not accessible. Use the format: [Enter a valid] [label descriptor] [label type] [example].
For example: Enter a valid email address. For example: name@email.com
Character count:
For a counter that actively counts characters, use this text: Character count: 0/max
For example: Character count: 0/100
Placeholder text
Follow the writing guidelines for placeholder text.
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.
Make sure you define ARIA labels for the selection inputs that are aligned with the language context of your application.
More accessibility guidelines.