layout: documentation title: Beautiful error messages
Beautiful error messages
Status: Reviewed, not yet implemented
Author: laurentlb@google.com
Reviewers: ulfjack@google.com
Related: Implementing beautiful error messages
Background
Providing good error messages is important for usability. It is especially important for new users who try to understand a tool. It can also drive adoption (as in clang vs gcc).
I suggest we make error messages in Bazel more helpful.
Other tools
Screenshots below are from Elm and Clang, both have been praised for the quality of their diagnostics. They are good examples we can draw our inspiration from.
See also [Compiler Errors for Humans] (http://elm-lang.org/blog/compiler-errors-for-humans), a blog article about the work that went into Elm.
What we can improve
- Users need context: Showing exact code in error is useful (with a caret ^). Currently location in Bazel error messages is often approximative (e.g. column number is often off, we show location of a rule instead of the specific attribute).
- Colors make messages easier to understand.
- Suggestions are useful. Bazel should try to guess what the user wanted to do, and suggest a fix. A typical example is to detect typos.
- A link can give more more information (e.g. elm can show a link to https://github.com/elm-lang/elm-compiler/blob/master/hints/recursive-alias.md). If you don’t, users will have to copy error messages and look up on search engine.
We have some limitations though:
- Due to memory constraints, we cannot keep the source file or even the AST after loading phase. Maybe code printing can be limited to errors in loading phase?
- Code generated through macros can make error reporting more difficult.
Examples
In each example below, you’ll find 1. the input code, 2. the current output from Bazel, 3. a suggested improvement.
These are just suggestions we can iterate on.
Input:
Current:
Suggested:
Input:
Current:
Suggested:
Input:
Current:
Suggested:
Input:
Current:
Suggested:
Input:
Current:
Suggested:
Input:
Current:
Suggested:
Input:
Current:
Suggested:
Input:
Current:
Suggested:
Input:
Current:
Suggested:
Input:
Current:
Suggested:
Input:
Current:
Suggested:
Input:
ext.bzl
BUILD
Current:
Suggested:
Suggestions
- Symbol not found during evaluation
- Suggest another symbol from the environment
- Invalid label (parse error)
- Link to label documentation, suggest a fix
- Directory of the label doesn’t exist
- Look in file system and suggest another directory
- Label name not found
- Suggest another name, from the same package
- Keyword argument doesn’t exist
- Suggest name, based on function signature
- Field not found (obj.nonexistent)
- Suggest name, based on list of fields
Action items
- Show context line + carret
- Suggest spelling fixes
- Show documentation links
- Show expanded rules (for action conflicts or errors during analysis phase)
- Improve error messages for rules developers (e.g. pretty-print action graph?)
- Review existing error messages + add ad-hoc suggestions