Errors

An error occurs after a user takes an action but, either the expected result doesn’t happen — or nothing happens. (If you need to communicate potential issues before a user takes action, use a warning. Components that include warnings statuses are Banner, Callout, and Toast.)

Errors can cause frustration, confusion, data loss, or rework for users. Error messages are one of the most important content elements in our UI and one of the 5 quality components of usable experiences.

 

Design to prevent errors

Before you write error messages, try to prevent errors from occurring in the first place. Partner with your engineers and PM to understand possible error states and try to find ways to avoid the error altogether by guiding users with:

  • Visual cues: Help users understand when and where they need to make a selection or entry. For example, identify optional fields.
.

.

  • Disabled states or controls: Prevent users from submitting incomplete information that will trigger errors. For example, disable the primary action button on the page until all required information has been provided.
  • In-line validation: Display an error as soon as users have finished filling out a field, without users needing to submit the field. After the field has an error, remove the error state once their input is valid. Use inline validation whenever possible.  See Text field.

Make error messages clear and useful

Good error messages answer two questions as clearly and concisely as possible:

  1. What went wrong.
  2. How to fix the problem.
  • If there’s no solution, suggest next steps if possible: Try again later. or Contact support for help.

 

How to write error messages

Be specific

Create unique, specific error messages that tell users how to solve the error. Don’t rely on repeating a default message.

Be concise

Give users only the information they need to solve errors. Generally, error messages are the least conversational UI content.

Use general language

It’s usually unnecessary to include filenames, usernames, or other specifics. Use general terms that can cover the most use cases and be localized more easily.

Use language that all users can understand

Include technical terms only when the detail helps solve the error and the users will understand them. For product errors, this includes removing or minimizing the use of error codes.

Use consistent language

Repeat the same vocabulary as the feature, the screen, and the component for clarity. In UI content, repetition helps build a user’s mental model and maintain clarity. Using synonyms for variety can confuse users.

Be supportive

Give users the information they need to correct errors, especially if errors are complex. This will reduce user frustration and rebuild their trust when using the product.

Don’t blame the user

Users should feel encouraged to take action to correct the issue rather than blamed for causing it. Avoid blame by not using you when explaining the error or using passive voice if needed.

Don’t be overly polite or apologetic

Avoid using please and sorry unless the error was caused by Okta and has severe consequences, such as requiring rework.

  • Saying sorry in error messages can make the situation worse by causing errors to appear more severe.
  • Similarly, saying please could make users think a required action is optional. And, saying please repeatedly makes attempts at politeness arbitrary and potentially insincere.

Don’t use humor

Errors are a negative experience for users. Humor can cause frustration, be misinterpreted or delay users fixing the error. In Okta products, never use Oops! or Uh-oh.

Generic errors

Sometimes errors have so many potential causes or are so major, we can’t clearly and concisely provide details. In these cases, users have no way to understand what went wrong or how to fix it.

In these cases, use a generic error.

Here, please is allowed because it's our error and inconceniences the user.

Here, please is allowed because it's our error and inconceniences the user.

Generic errors can be customized to offer an action.

Generic errors can be customized to offer an action.

Generic errors can be customized to explain as much as we know about the error as well.

Generic errors can be customized to explain as much as we know about the error as well.

Errors when a page or system is unavailable

Use these generic errors when:

  • A server error is preventing an entire page from being displayed, like with 400- or 500-series server errors.

Error message types and components

Inline error

Inline errors are concise, in-context errors that tell users what went wrong with an input or group of inputs and how to fix it.

There are generally three types of inline error messages:

  1. The user didn’t include information that was required. The default format for this kind of error is: Enter {your/the/a} {field label}, such as Enter your name. or Enter a group.
  2. The information didn’t pass validation. The text should be actionable and explain to the user what they need to do to proceed. For example: Enter a complete email address, such as you@okta.com.
  3. The information can’t be saved due to a product error. The text should explain what happened and prompt the user to try again. For example: There was a problem {validating your input/saving your entry}. Please try again.

Inline errors are the most frequent type and occur in these components:

Multiple inline errors

In rare cases, inline errors may include multiple errors. This is most commonly seen with the password variant of text field. Although, all input fields are built to allow multiple inline errors.

Each error should receive its own bullet point.

Double Error

Banner

An error banner should be used:

  • When you have system-wide error messages that require user attention.
  • When you need an error displayed according to the system settings (this could be a single view, a time period, or until an action is completed).
  • When you have multiple inline errors in a form and need an overarching banner to summarize them and drive users to fix them.

See Banner

 

Callout

An error callout should be used:

  • When the error is confined to a specific area in the UI.
  • When the error needs to persist until it is fixed or dismissed by the user.
  • When you need the alert to be in context of a specific area.

See Callout

 

Toast

An error toast should be used:

  • When the error is noncritical.
  • When you need to immediately confirm a user’s action failed.
This is the maximum amount of information a toast should contain. Ideally, a toast would only communicate Unable to save.

This is the maximum amount of information a toast should contain. Ideally, a toast would only communicate Unable to save.

To communicate this level of detail, explore a different alert, like an inline alert.

To communicate this level of detail, explore a different alert, like an inline alert.

See Toast

 

Empty states

Two of the three empty state variants are errors.

A system error empty state:

  • Tells users when there is data but it can’t be surfaced due to a lack of proper permissions, configurations, or other reasons.
  • Explain the problem and tell the user what action to take to correct the issue and populate or access the data.

An user action empty state:

  • Explains why the data is unavailable and what the user can do, if anything, to display the data.

 

See Empty states

 

Have questions or need support?

Oktanauts can use the following resources when building with Odyssey:

  • Check the Odyssey 1.0 FAQs.
  • Join #odyssey in Slack and tag @content to ask questions.
  • Attend Odyssey Office Hours on Mondays and Wednesdays from 1-1:30 p.m. PT / 4-4:30 p.m. ET.
  • Submit bug reports and feature requests to the Odyssey Jira board
  • Request a new component using the Odyssey component proposal.