Introduction 

Briefly write the need for this feature

Goals

Clearly state the design goals/requirements for this feature 

User Stories 

• Breakdown of User-Stories 
• User Story #1
• User Story #2
• User Story #3

Design

Cover details on assumptions made, design alternatives considered, high level designAn 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

Contextual Error messages

Error messages without any context are very hard to interpret. Contextual information can be 

For example, if there is a mismatch in data type of a field, error message with more contextual information 

Error Message:
Data type mismatch for field 'X'. 


Better Error Message:
Field 'X' has data type Provided Data type Int 

Fail Fast

Validation Errors

No implementation details in User facing Error Messages

Prefer specific error messages instead of generic error messages

Configuration parameters

Avoid Throwables.propagate()

Throwables.propagate(t) will throw t as-is if it is a RuntimeException. If it is a checked exception, it will throw a RuntimeException with the checked exception as it's cause.

If the throwable is a RuntimeException that should be propagated, there should have been no reason to catch it to begin with.

If the throwable is a checked exception, it should probably be handled right there or it should be propagated as-is.

Throwables.propagate() is usually used as a lazy way "handle" exceptions. It usually ends up in ignoring an exception that should not be ignored.

Any exception thrown by an HTTP Handler should be written with a UI user in mind. It should be assumed that the exception message will show up in the UI. Overly long messages should be avoided. In particular, beware of messages that are generated based on data in some collection. Messages must not contain sensitive information, such as secure keys.

• Exception messages should contain all the information required by the caller to understand what caused the exception. The message should contain the values of all parameters and fields that contributed to the exception. For example, if the an exception occurred because an application could not be found, the application name should be included in the exception message. If a dataset could not be created, the message should include the dataset name. When possible, include any information the caller would find useful to avoid the exception. For example, if an invalid value is given, include what the valid values are.
  
  
• Do not add any sensitive information in error messages such as passwords or credit card information.
• Write a separate error message for each known cause of the error whenever possible. Do not use a single, generic message to explain every possible reason for the error unless you cannot determine the cause of the error when it occurs.

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

Deprecated REST API

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

Releases

Release

6.

1.0

Related Work

• Work #1
• Work #2
• Work #3

Future work