Error Messages in I3DS

Error messages play a critical role in user experiences by addressing disruptions, guiding resolution, and minimizing frustration. A well-designed error message helps users understand what happened, why it occurred, and how to move forward.

What is an Error?

An error occurs when users expect one thing to happen, but something unexpected or nothing at all happens. Errors can lead to frustration, confusion, data loss, or additional work. Error messages should aim to inform and support users, minimizing the impact of the disruption.

Principles for Designing Error Messages

1. Avoid Errors Where Possible

The best error message is no error message. The message, and the error itself are disruptive to a user’s experience and can stand in the way of them accomplishing their task. Anticipate potential issues and address them in the design or system logic before users encounter them.

Find ways to avoid the error altogether:

In-Line Validation: Provide real-time feedback as users interact with inputs, such as marking fields with visual cues when they require specific formats or values.
Visual Cues and Disabled States: Use design elements like disabled buttons or fields to guide users toward valid actions before they submit incorrect data.
Anticipate User Behavior: Design systems to handle variations or unexpected inputs gracefully. For example, accepting different date formats or accommodating misspellings in search queries.

Do

Use the disabled states of components to communicate that next steps are unavailable unless a user takes an action first.
Don't

Don't create unnecessary error messages as a workaround to unintuitive design.

2. Automatically resolve errors

When errors do occur, aim to resolve them on the system's end without disrupting the user experience.

Do
- Automatically adjust out-of-range values to the nearest valid number.
- Inform the user subtly about the adjustment (e.g., a tooltip or helper text).
Don't
- Don't create unnecessary error messages as a workaround to unintuitive design.

3. Choose the Message First, Then the Component

Error messages should always be crafted before deciding how to display them. Misalignment between the message content and the chosen UI component can lead to confusion or frustration. For example, a detailed error message in a temporary toast notification may not give users enough time to read or act on it, while a simple error in an alert dialog may unnecessarily disrupt their workflow.

Write the Message First
Evaluate the Error Context
Choose the Right Component After crafting the message, select the appropriate UI component based on the error’s context:
Test for Usability

Component	When to Use
Alert Dialog	For high-consequence, high-complication, and actionable errors that require user acknowledgment or decisions (e.g., invalid credentials or data loss).
Alert Banner	For high-priority system-level errors that need visibility but don’t block the user’s workflow (e.g., connection loss or server issues).
In-Line Alert	For errors tied to specific inputs or fields, especially when multiple errors can be aggregated (e.g., form validation).
Help Text	For low-complication input errors, providing immediate guidance or hints about required formats (e.g., "Password must be at least 8 characters long").
Toast Notification	For low-consequence, transient errors that don’t require immediate attention or further action (e.g., “Action failed. Try again later.”).

Anatomy of an error message

Error messages are often highly visible and memorable, so they must be relevant, clear, and actionable. They should focus on: 1. What happened. 2. The cause of the error (if relevant). 3. How to resolve it.

Not every error message you'll write will follow this framework, but many will. Depending on your audience or the situation, it may not be necessary or relevant to communicate the underlying cause.

1. What Happened

The first part of an error message should clearly communicate the general outcome of the issue. This serves as a headline (if the UI element allows) and helps users quickly understand what went wrong. Use plain, concise language that focuses on the user's perspective and what the error means for their task or goal.

Guidelines for Communicating What Happened:

Use Plain Language: Avoid technical jargon or overly complex explanations. Make the message easy to understand for users of all skill levels.
Focus on the User's Experience: Provide enough detail to help users understand the issue at a glance, especially if the error is tied to a particular action or feature.
Avoid Negative Framing: While the message communicates a failure, keep the tone neutral and informative. Avoid overly negative or accusatory language.

Do
- Automatically adjust out-of-range values to the nearest valid number.
- Inform the user subtly about the adjustment (e.g., a tooltip or helper text).
Don't
- Don't create unnecessary error messages as a workaround to unintuitive design.

2. The cause of the error (if relevant).

When space and context allow, it can be helpful to explain why an error occurred. Providing an explanation can enhance a user's understanding and potentially reduce frustration. However, it’s important to evaluate whether the additional information adds value or merely distracts from resolving the issue.

Guidelines for Explaining the Cause:

Provide Relevant Context: If the cause helps users understand what went wrong or how they can avoid the error in the future, include it. Avoid unnecessary technical details or blame.
Consider the User’s Perspective: Keep explanations user-centered and focus on how the cause impacts their task.
Be Concise: Use as few words as possible to explain the cause while remaining clear. Overly detailed or vague descriptions can confuse users.
Make It Optional When Necessary: If the cause doesn’t directly help the user resolve the issue, it may be better to leave it out. Instead, focus on what they can do next.

Do
- Automatically adjust out-of-range values to the nearest valid number.
- Inform the user subtly about the adjustment (e.g., a tooltip or helper text).
Don't
- Don't create unnecessary error messages as a workaround to unintuitive design.

3. How to resolve it.

The final part of an error message should guide the user on how to resolve the issue. This step is essential for empowering users to move forward with confidence. If there’s nothing the user can do, explain what the system is doing to resolve the issue on their behalf. The guidance should be as simple, clear, and actionable as possible.

Guidelines for Providing a Solution:

Be Actionable: Clearly outline what steps the user can take to fix the issue. Use verbs to guide them toward resolution.
Explain System Actions: If the error is being handled automatically by the system, communicate this to reassure the user.
Provide Specific Guidance: Avoid vague instructions or generic advice like "Contact your IT administrator" unless absolutely necessary. If external resources are required, link to a specific, detailed help article.
Offer Immediate Solutions: Include interactive elements within the error message whenever possible, such as buttons or links to retry an action, go back, or proceed with an alternative.

Do
- Automatically adjust out-of-range values to the nearest valid number.
- Inform the user subtly about the adjustment (e.g., a tooltip or helper text).
Don't
- Don't create unnecessary error messages as a workaround to unintuitive design.

Be empathetic to users

Error messages should prioritize the user’s experience, not the constraints or technicalities of the system. Users are likely already frustrated when encountering an error, so the tone and content of the message should feel supportive and helpful rather than cold, technical, or accusatory.

Guidelines for Writing Empathetic Error Messages:

Focus on the User’s Perspective: Write messages centered on what the user was trying to do, rather than what the system failed to do. Avoid shifting blame onto the user.
Use Supportive Language: Frame the error in a way that reassures the user and shows that the system is working to resolve the issue.
Avoid Jargon or Technical Explanations: Most users don’t care about the underlying system constraints or technical terms. Use plain, clear language that conveys the issue in a way they can understand.
Offer Clear, Actionable Guidance: When applicable, provide users with steps to resolve the issue without making them feel at fault.
Acknowledge the User’s Effort: Show that you value their time and effort by recognizing what they were trying to accomplish.

Be as useful

Error messages should empower users by providing them with clear, actionable guidance. Every error message is an opportunity to help users move forward confidently, and it should prioritize what they can do rather than focusing solely on the problem.

Guidelines for Writing Useful Error Messages:

Focus on the Solution: Provide a clear path to resolution within the message or error state. Users need to know how to fix the issue or what the system is doing to resolve it.
Prioritize Actionability: Offer actionable advice or steps users can take to resolve the problem. Include options like retrying an action, adjusting a setting, or linking to specific resources.
Use Positive Framing: Avoid negative or overly restrictive language. Instead, focus on what users can do to resolve the issue or move forward.
Include Context Where Necessary: Explain the error in context, but only if it helps the user understand the problem and its resolution. Avoid overwhelming them with unnecessary details.
Link to Specific Resources: When additional help is required, link users to specific, relevant documentation or support articles. Avoid generic or catch-all instructions.
Provide Immediate Next Steps: Make the next step clear and easy to execute, such as retrying, changing input, or contacting support with specific information.

Writing the error messages

Error messages should guide users with clear, concise, and actionable language while maintaining a tone that feels empathetic and supportive. The goal is to minimize frustration and provide the user with confidence to resolve the issue or understand what’s happening.

Key Principles for Writing Error Messages

Clarity and Simplicity: Use plain language that avoids jargon or technical terms unless absolutely necessary. Focus on what the user needs to know to understand the issue and resolve it.
Empathy and Support: Use a tone that shows understanding and support. Avoid language that feels accusatory or overly formal.
Actionable Guidance: Provide clear, specific instructions on how to resolve the issue or what to do next.
Context Where Needed: Explain why the error occurred if it’s relevant and helpful to the user. Avoid overwhelming them with unnecessary details.
Be Positive and Focus on Solutions: Avoid negative or overly dramatic language. Highlight what the user can do rather than dwelling on what went wrong.
Audience Appropriateness: Adjust the tone and technical depth of the message based on your audience. For general users, use non-technical language; for developers or advanced users, include relevant technical details.