An error message is the text used to provide information about error situations. Poorly written error messages can increase support costs and can be a source of frustration for users. Well-written error messages are very important for better user experience. Below is the best practices on writing better error messages.
1. Error messages should be contextual.
Contextual error messages provide specific information particular to error situation. Error messages without any context are very hard to interpret by users. Contextual information may include information such as why the error happened, what is the error value, what is the expected value, how user can fix the error etc.
For example, if there is a mismatch in data type of a field, providing more contextual information to user in error message would help user understand the problem and fix it if needed.
2. Do not include implementation details in user facing error messages.
Exposing implementation details to end users can be confusing and users may not be able to take any action to solve error situation. Thats why user facing error messages should not include implementation details. Below are some of the cases where we can avoid exposing implementation details:
Avoid using class hashes in error messages. For example:
Avoid using exception class names in user facing error messages. For example:
Avoid using technical implementation details in user facing error messages. For example:
3. Error message should provide direction to user if action is needed from user.
An error message has 3 parts, problem identification, cause details if helpful, and a solution if possible. Whenever error situation occurs, users would like to fix it immediately. The error message should have enough information to guide the user in right direction.
4. Provide complete concise error message to user and avoid ambiguity.
An error message should be a complete sentence which provides clear message. User should be able to understand the problem by reading the error message. For example:
5. Always prefer error message specific to the error situation instead of generic error messages
Whenever possible, use specific error message instead of generic error message. For example: