layout: global title: Error message guidelines type: “page singular” navigation: weight: 5 show: true

Error Message Guidelines

This guide is a reference for composing standardized and actionable error messages in Apache Spark.

Include What, Why, and How

Exceptions thrown from Spark should answer the Five W's and How:

  • Who encountered the problem?
  • What was the problem?
  • When did the problem happen?
  • Where did the problem happen?
  • Why did the problem happen?
  • How can the problem be solved?

The context provided by exceptions can help answer who (usually the user), when (usually included in the log via log4j), and where (usually included in the stack trace). However, these answers alone are often insufficient for the user to solve the problem. An error message that answers the remaining questions --- what, why, and how --- minimizes user frustration.

Explicitly answer What, Why and How

In many cases, the error message should explicitly answer what, why, and how.

Example 1
  • What: Unable to generate encoder inner class.
  • Why: Did not have access to the scope that the class was defined in.
  • How: Try moving this class out of its parent class.
Example 2

If the proposed fix (how) feels arbitrary, providing an explanation for why the error occurred can reduce user frustration.

Before

  • What: Unsupported function name.
  • Why: Unclear.
  • How: Unclear.

After

Function name {} is invalid. Temporary functions cannot belong to a catalog. Specify a function name with one or two parts.

  • What: Invalid function name.
  • Why: Temporary functions cannot belong to a catalog.
  • How: Specify a function name with one or two parts.

Implicitly answer How

Not all error messages should be this verbose. Sometimes, explicitly explaining how to resolve the problem would be redundant; you may skip an explicit explanation in this case.

Example 1
  • What: Invalid pivot column.
  • Why: Pivot columns must be comparable.
  • How (implied by Why): Use comparable pivot columns.
Example 2

Before

  • What: Cannot specify window frame for the function.
  • Why: Unclear.
  • How: Unclear.

After

  • What: Cannot specify the frame for the window expression.
  • Why: Window expression contains mismatch between function frame and specification frame.
  • How (implied by Why): Match the function frame and specification frame.
Example 3

Before

  • What: Cannot parse decimal.
  • Why: Unclear.
  • How: Unclear.

After

  • What: Invalid decimal.
  • Why: The decimal parser encountered an error at the specified position.
  • How (implied by Why): Fix the error at the specified position.

Implicitly answer Why and How

Sometimes, even explicitly explaining why the problem happened would be redundant; you may skip an explicit explanation in this case.

  • What: Path does not exist.
  • Why (implied by What): User specified an invalid path.
  • How (implied by What): Use a different path.

Use clear language

Diction guide

Wording guide