Versions Compared


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


  • Errors should not cause running servers (e.g. a database node) to terminate immediately. Customers would cause consider this an unacceptable defect. Correct and deliberate error handling is a core part of product quality and stability.

  • Users will read the text of error messages, however users cannot be assumed to understand the source code. If an error message is confusing, the users will ask confused questions to our tech support. If an error message is misguiding, the users will ask the wrong questions to our tech support. And so on. Error messages should be clear and accurate and avoid referring to source code internals.

  • Any error visible to one user will likely be visible to dozens, if not thousands of users eventually. We want our users to understand what they should do about an error on their own, so they do not need to reach out to technical support. For this, we want our error messages to be self-explanatory and include hint annotations. We also make specific error codes (e.g. SQLSTATE) part of our public, documented API for using CockroachDB.

  • Errors are part of the API and thus error situations should be exercised in unit tests.

  • Error make their way to log files and crash reports and can contain user-provided data. We care to separate customer confidential data from non-confidential data in log files and crash reports, and so we need to distinguish sensitive data inside error objects too.