Checklist
- User Stories Documented
- User Stories Reviewed
- Design Reviewed
- APIs reviewed
- Release priorities assigned
- Test cases reviewed
- Blog post
Introduction
what is the motivation for this exercise
An error message is text that is displayed to describe a problem that has occurred that is preventing the user or the system from completing a task. The problem could result in data corruption or loss. Other message types include confirmations, warnings, and notifications. The guidelines in this topic are intended to help you write clear error messages that are easy to localize and useful for customers.
Goals
The goals of this wiki page is to provide guideline on writing better error messages and also improve error message in Dataprep, Plugins and CDAP platform.
Guidelines for Error Messages
1. Make error messages more 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.
Error Message: Data type mismatch for field 'X'. Better Error Message: Field 'X' is of data type 'int' in the schema. However, provided data type is 'string'.
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:
Error Message: co.cask.directives.language.SetCharset@781ecbac : Invalid type 'java.lang.String' of column 'body'. Should be of type String. Better Error Message: Error executing 'set-charset' directive: The 'body' column was expected to be a byte array or ByteBuffer, but is of type 'String'.
Avoid using exception class names in user facing error messages. For example:
Error Message: java.lang.IllegalArgumentException: Database driver 'cloudsql-postgresql' not found. Better Error Message: Database driver 'cloudsql-postgresql' not found. Please make sure correct database driver is deployed.
Avoid using technical implementation details in user facing error messages. For example:
Error Message: Failed to configure pipeline: valueOf operation on abc failed. Better Error Message: Failed to configure pipeline: Expected type of field 'X' is either int/double but found 'abc'.
3. Add call to action for error
4. Provide concise error message to user and avoid ambiguity
should not include cryptic error messages which can not be interpreted by end users
5. Always prefer error message specific to the error situation instead of generic error messages
6. Consistent error messages
7. Validation Errors
Validate for empty string/ null string before using the text in error message
8. Configuration parameters
9. Error message style considerations
Bug Fixes
Approach
Approach #1
Approach #2
API changes
New Programmatic APIs
New Java APIs introduced (both user facing and internal)
Deprecated Programmatic APIs
New REST APIs
Path | Method | Description | Response Code | Response |
---|---|---|---|---|
/v3/apps/<app-id> | GET | Returns the application spec for a given application | 200 - On success 404 - When application is not available 500 - Any internal errors | |
Deprecated REST API
Path | Method | Description |
---|---|---|
/v3/apps/<app-id> | GET | Returns the application spec for a given application |
CLI Impact or Changes
- Impact #1
- Impact #2
- Impact #3
UI Impact or Changes
- Impact #1
- Impact #2
- Impact #3
Security Impact
What's the impact on Authorization and how does the design take care of this aspect
Impact on Infrastructure Outages
System behavior (if applicable - document impact on downstream [ YARN, HBase etc ] component failures) and how does the design take care of these aspect
Test Scenarios
Test ID | Test Description | Expected Results |
---|---|---|
Releases
Release 6.1.0
Related Work
- Work #1
- Work #2
- Work #3