Versions Compared

Old Version 2

changes.mady.by.user Vinisha Shah

Saved on

compared with

New Version 3

changes.mady.by.user Vinisha Shah

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

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

Contextual Error messages

Error

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 can be 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, error message with more contextual information providing more contextual information to user in error message would help user understand the problem and fix it if needed. 

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


Better Error Message:
Field 'X' hasis of data type Provided Data 'int' in the schema. However, provided data type Intis

Fail Fast

Validation Errors

No 
'string'.

2. Do not include implementation details in

User

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.

    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:

      No Format
      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:

      No Format
      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:

      No Format
      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

    PathMethodDescriptionResponse CodeResponse
    /v3/apps/<app-id>GETReturns the application spec for a given application

    200 - On success

    404 - When application is not available

    500 - Any internal errors







    Deprecated REST API

    PathMethodDescription
    /v3/apps/<app-id>GETReturns 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 IDTest DescriptionExpected Results












    Releases

    Release 6.1.0

    Related Work

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


    Future work