Link Search Menu Expand Document (external link)

Handling errors

Users will encounter errors in all software, regardless of our level of quality. We should endeavor to make the experience painless, properly set expectations, and direct the user to a quick resolution. There are a few ways to report an error:

  • Use form field validation if the problem can be isolated to a particular form input, we can catch the problem onblur, and the user can correct the problem
  • Use an inline alert when the user is completing a form and we want to keep them on the form (to retry or to report the form contents to support). Inline alerts are also a good choice if a screen element cannot be drawn due to an error or missing data.
  • Use an asynchronous notification or email when a background task runs into problems
  • Use a modal dialog for other cases

Form field validation and inline alerts

Example form with an invalid value supplied for a text input

When placing error messages, we use a simple, three-part rubric:

Show the error as close as possible to the input control with a value that needs attention

Show the error as close as possible to the last thing the user messed with before we detected the error

If 1 and 2 are close together, show one error on the input control. If 1 and 2 are far apart, show two messages.

Example form with an reporting a failed secondary operation

For more complex screens (or screens with more complex errors), consider stealing space from other components. For example, if a code editor has an output console, draw the error message in the space reserved for the output console.

Asynchronous Notifications

Occasionally the user will start a long-running operation and navigate away from the page where the operation was started. In some cases they may log out of the application entirely. When one of these operations fail, notify the user via an asynchronous channel (email or slack). Use the Unexpected Failures guidance for the structure and content of these notifications.

Modals should contain:

  • Situation: Why is this message appearing on my screen?
  • Status: If I requested work to be done, what’s the status of the work?
  • Reason: If there is some rule which is blocking the action, explain the rule. If this is an unexpected code error, be honest.
  • Guidance: What steps can I take to correct the problem? Where should I look for more information?

If appropriate, more information may be hidden behind a progressive disclosure (stack traces, internal error codes, etc). Keep your audience in mind; technical users are likely to want to know where to find logs or protocol specifications.

For example, suppose I attempted to delete a table and the attempt failed. The dialog should tell me:

  • Situation: An operation failed
  • Status: The table was not removed; it’s still there
  • Reason: Another user has a lock on the table and tables cannot be deleted while in use
  • Guidance: Contact the other user or follow some documented procedure to force deletion

Success

It’s not always bad news. Most operations require no confirmation that they have been performed successfully. Make an exception when:

  • Completing the operation has generated useful new information
  • The operation was only partially successful
  • The behavior of the operation is occult or unpredictable and it is useful to explain what just happened

Use a snackbar when there is little information to report. Use other mechanisms (dialog, full screen, downloadable report) as necessary.

Error Messaging Dos:

  • Explain what went wrong using language the user understands.
  • If there are esoteric details which are only useful to support, hide them under a progressive disclosure. Make it easy to copy-paste them.
  • If the user can correct the problem, provide guidance on how.
  • If the problem is complex, link to supporting documentation.
  • If the problem can be localized to a particular screen element or input field, show the error messaging (and guidance) near that screen element.

Error Messaging Don’ts:

  • Don’t use jargon, internal code names, or error codes.
  • Don’t show stack traces by default.
  • Don’t automatically hide error messages. Don’t make it easy to accidentally hide them.
  • Don’t encourage the user to “try again later” unless we’ve very certain that this is a transient error that is likely to fix itself automatically.
Copyright © 2022 FeatureBase, Inc.