---
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](/designs/2016/05/26/implementing-beautiful-error-messages.html)
## 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:
my\_obj = select({
":something": [1],
"other": [2],
})
t = [x for x in my\_obj]
Current:
ERROR: /path/BUILD:6:5: type 'select' is not iterable
Suggested:
ERROR: /path/BUILD:6:16: my\_obj of type 'select' is not iterable. You can iterate only on string, lists, tuples, or dicts.
t = [x for x in my\_obj]
^-----
Related documentation: http://www.bazel.build/docs/be/functions.html#select
***
Input:
t = [x for x in]
Current:
ERROR: /path/BUILD:1:16: syntax error at ']': expected expression
Suggested:
ERROR: /path/BUILD:1:16: Syntax error: expected expression, got ']'.
t = [x for x in]
^
***
Input:
glob(["*.cc"], excludes = ["foo.cc"])
Current:
ERROR: /path/BUILD:1:1: unexpected keyword 'excludes' in call to glob(include: sequence of strings, exclude: sequence of strings = [], exclude\_directories: int = 1)
Suggested:
ERROR: /path/BUILD:1:5: 'excludes' is an invalid keyword argument for the function glob(include, exclude, exclude\_directories). Did you mean exclude?
glob(["*.cc"], excludes = ["foo.cc"])
^-------
exclude
Related documentation: http://www.bazel.build/docs/be/functions.html#glob
***
Input:
cclibrary(name = "x")
Current:
ERROR: /path/BUILD:1:1: name 'cclibrary' is not defined
Suggested:
ERROR: /path/BUILD:1:1: Name 'cclibrary' is not defined. Did you mean cc\_library?
cclibrary(name = "x")
^--------
cc\_library
***
Input:
cc\_library(
name = "x",
deps = ":lib",
)
Current:
ERROR: /path/BUILD:1:1: //test:x: expected value of type 'list(label)' for attribute 'deps' in 'cc\_library' rule, but got ":lib" (string)
Suggested:
ERROR: /path/BUILD:3:5: Expected value of type 'list(string)' for attribute 'deps' in 'cc\_library' rule, but got ":lib" (string). Did you mean [":lib"]?
deps = ":lib",
^-----
[":lib"]
Related documentation: http://www.bazel.build/docs/be/c-cpp.html#cc\_library
***
Input:
VAR = ":lib"
cc\_library(
name = "x",
deps = VAR,
)
Current:
ERROR: /path/BUILD:3:1: //test:x: expected value of type 'list(label)' for attribute 'deps' in 'cc\_library' rule, but got ":lib" (string)
Suggested:
ERROR: /path/BUILD:5:5: Expected value of type 'list(string)' for attribute 'deps' in 'cc\_library' rule, but got ":lib" (string). Did you mean [VAR]?
deps = VAR,
^--
[VAR]
Related documentation: http://www.bazel.build/docs/be/c-cpp.html#cc\_library
***
Input:
cc\_library(
name = "name",
deps = ["/test/foo.cc"],
)
Current:
ERROR: /path/BUILD:1:1: //test:name: invalid label '/test/foo.cc' in element 0 of attribute 'srcs' in 'cc\_library' rule: invalid target name '/test/foo.cc': target names may not start with '/'
Suggested:
ERROR: /path/BUILD:3:13: Invalid label '/test:foo.cc' in deps. Labels relative to the root start with //. Did you mean '//test:foo.cc'?
deps = ["/test:foo.cc"],
^-------------
"//test:foo.cc"
Related documentation: http://www.bazel.build/docs/build-ref.html#labels
***
Input:
cc\_library(
name = "name",
srcs = [":x"],
)
genrule(
name = "x",
outs = ["file.ext"],
cmd = "touch $@",
)
Current:
ERROR: /path/BUILD:3:12: in srcs attribute of cc\_library rule //test:name: '//test:x' does not produce any cc\_library srcs files (expected .cc, .cpp, .cxx, .c++, .C, .c, .h, .hh, .hpp, .hxx, .inc, .S, .s, .asm, .a, .pic.a, .lo, .pic.lo, .so, .dylib, .o or .pic.o)
Suggested:
ERROR: /path/BUILD:3:12: In srcs attribute of //test:name (cc\_library), '//test:x' does not produce any cc\_library srcs files (expected extension .cc, .cpp, .cxx, .c++, .C, .c, .h, .hh, .hpp, .hxx, .inc, .S, .s, .asm, .a, .pic.a, .lo, .pic.lo, .so, .dylib, .o or .pic.o). Target //test:x (genrule) generated 'file.ext'.
Related documentation: http://www.bazel.build/docs/be/c-cpp.html#cc\_library
***
Input:
cc\_library(
name = "name",
deps = ["//base:scheduling\_domain-test"],
)
Current:
ERROR: /path/BUILD:1:1: in cc\_library rule //test:name: non-test target '//test:name' depends on testonly target '//base:scheduling\_domain-test' and doesn't have testonly attribute set
Suggested:
ERROR: /path/BUILD:3:5: In deps attribute of //test:name (cc\_library), '//base:scheduling\_domain-test' (cc\_library) is marked as testonly. You may either add:
testonly = 1
to //test:name definition, or remove testonly from //base:scheduling\_domain-test, or remove the dependency.
Related documentation: http://www.bazel.build/docs/be/common-definitions.html#common.testonly
***
Input:
cc\_library(
name = "name",
srcs = ["//base:arena.cc"],
)
Current:
ERROR: /path/BUILD:1:1: Target '//base:arena.cc' is not visible from target '//test:name'. Check the visibility declaration of the former target if you think the dependency is legitimate
Suggested:
ERROR: /path/BUILD:3:5: In srcs attribute of //test:name (cc\_library), '//base:arena.cc' (file) is not visible. You may change the visibility of the file using exports\_file, or expose the file via a library rule, or remove the dependency.
//base:arena.cc has currently private visibility.
Related documentation: http://www.bazel.build/docs/be/common-definitions.html#common.visibility
***
Input:
cc\_binary(
name = "bin",
deps = [":lib"],
)
cc\_library(
name = "lib",
srcs = [":src"],
)
genrule(
name = "src",
outs = ["file.cc"],
cmd = "touch $@",
tools = [":bin"],
)
Current:
ERROR: /path/BUILD:1:1: in cc\_binary rule //test:bin: cycle in dependency graph:
//test:bin
//test:lib
//test:src
\* //test:bin (host)
//test:lib (host)
//test:src (host)
\* //test:bin (host)
Suggested:
ERROR: /path/BUILD:1:1: Cycle in dependency graph detected:
cc\_binary //test:bin depends on (via deps):
cc\_library //test:lib depends on (via srcs):
genrule //test:src depends on (via tools):
\* cc\_binary //test:bin [host] depends on (via deps):
| cc\_library //test:lib [host] depends on (via srcs):
| genrule //test:src [host] depends on (via tools):
* cc\_binary //test:bin [host]
Please modify at least one of the dependencies to break the cycle.
***
Input:
ext.bzl
def foo(name):
native.genrule(
name = name,
outs = ["file.cc"],
cmd = "touch $@",
)
BUILD
load(":ext.bzl", "foo")
foo("src2")
files = ["file.cc"]
genrule(
name = "src",
outs = var,
cmd = "touch $@",
)
Current:
ERROR:/path/BUILD:7:1: generated file 'file.cc' in rule 'src' conflicts with existing generated file from rule 'src2'
Suggested:
ERROR: /path/BUILD:7:1: Generated file 'file.cc' in rule 'src' conflicts with existing generated file from rule 'src2'.
'src' is defined line 7:
genrule(
name = "src",
outs = ["file.cc"],
cmd = "touch $@",
)
'src2' is generated by the function foo (line 3) and is equivalent to:
genrule(
name = "src2",
outs = ["file.cc"],
cmd = "touch $@",
)
[Another case](https://github.com/bazelbuild/bazel/issues/1307)
## 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