Error Handling

Users need to know the errors that are stopping them from performing an action. We need a consistent way to display errors that guide the user to the place they need to recover.

When errors occur

• Errors typically occur when data input or a task fails on the server-side.
• System errors occur when the Octopus Server is down. These types of errors can be displayed at any time in the UI and don't rely on a user action.
• Inline validation can occur in both client-side and server-side.

The elements of the error pattern

An error pattern scenario can use one or multiple elements to alert the user.

1. The error panel

Display the error panel after a server-side task failed. The error panel should appear on the paper element or dialog where the user needs to perform and action to recover.

2. The error icon

Display an error icon after a server-side task has failed and when a user can navigate between different parts of the information before saving. For example, on tabs, step editor or side menu.

3. The inline validation

Display inline validation when a server-side task fails and when client-side validation is triggered.

 

---

Best practices

Do

✅ Avoid the user being in an error state
The best type of error is one that we can avoid. We would rather spend time refining the UX so the user understands what is required rather than using an anti-pattern.
✅ Display the error message on the page where the error occurred
The error message should appear in the location of the error the user needs to fix. For example, if a user was filling out a form in a dialog and clicked SAVE, the error message would appear in the dialog, not on the paper element behind it.
✅ Be clear and helpful with the content of the error message
The error message is made up of two parts and should clearly state the reason why an error occurred and the steps required to resolve the error.

• The heading should alert the user that something is wrong but not necessarily tell them the details.
• The content of the error message should clearly explain the problem and help the user recover from the error. Any identifiers are quoted with a single quote. Example 'Name' must not be empty.

✅ Use inline validation to show where the error occurred
If the error is within a form, use inline validation to help the user recover from the error.
✅ Use an icon identifier to show the user the location of an error
Use an error icon to guide the user to the location where the error needs to be fixed.

Don't

❌ When user can't recover.
For example, If the user performed an action in a dialog but the error is referring to the form in the paper element behind the dialog. Automatically close the dialog display the error on the form so the user can quickly and easily recover.

---

Scenarios

A scenario can use a combination of error elements. Where to display the error message depends on where the user needs to be to recover from the error and the action the user just performed.

• Error occurs client-side while user is editing a form
• Error occurs server-side after user tries to save data – form, dialog, tabs, step editor, task log
• Navigating away from a form in a dirty state

Error occurs client-side while user is editing a form

In some cases we detect validations before a user saves a form. Typically the form element will change state immediately to let the user know about the error.

Error occurs server-side after user tries to save data

If an error occurs while data is being saved on the server, an error panel is displayed on the paper element. If the error is because of an invalid form field, use inline validation and/or the error icon to guide the user to the location of which they can recover.

Error on a form in a paper element

Error on a form in a Dialog

User triggers action from a Dialog but the error is in the form behind it

Errors within tabbed content

Using Tabs

Process editor

Errors during a task

Example of a task error

Example of a deployment error

Navigating away from a form in a dirty state