Skip to main content

Error Reporting

Error reporting is a critical part of any user-facing process, and the tone and wording of the error messages can have a significant impact on the user experience.

Error handling​

If there is the possibility that an error could occur at a stage within a process, it is important to handle this gracefully and provide the user with clear and concise information on what has gone wrong and how to resolve it. Any known potential error should be accounted for and handled in a way that is user friendly; simply surfacing the underlying error message is not sufficient.

For example, imagine a screen flow which updates a related record when a user submits a form. If the lookup is not populated and a Null pointer exception is thrown, this error message shouldn't be directly shown to the user. Instead checks should be put in place to ensure that the lookup is populated before the record is updated, and if it is not, a user-friendly error message should be shown to the user.

Writing guidelines​

The following guidelines, based on the SLDS Voice and Tone guidelines, should be followed when creating error messages.

Be concise​

  • Use as few words as possible to convey the message
  • Keep it focused on the issue at hand
  • Avoid large blocks of text and long sentences

Be direct​

  • Use active voice, e.g. "Enter your name", not "Name not entered"
  • Use simple language, avoiding buzzwords and jargon that may not be understood by all users
  • Refer to items by their literal names

Do not use please​

Please should only be used in situations where the user is being inconvienced, or if the error is not their fault, such as a system error. It should not be used in the following scenarios:

  • When the user has made the mistake, such as not entering a required field
  • Validation rules

Do not use exclamation points​

These should only be used to encourage engagement or generate excitement, for example in a call to action or feedback during a process.

Be consistent​

Errors can be encountered across various parts of the application. Ensure that where similar errors are encountered, the messaging is consistent, allowing the user to more easily understand the issue and how to resolve it.

  • Good: Required field X is missing.
  • Bad: Fill out X before moving to the next screen.

Provide clear directions for resolution​

If the error is due to user input, provide clear instructions on how to resolve the issue, such as which fields are missing or incorrect.

  • Good: Opportunity amount must not be negative.
  • Bad: Opportunity amount is invalid.