Beautify Bazel configuration errors #11984

gregestren · 2020-08-20T19:56:51Z

tl;dr: apply beautiful error principles to build failures from analysis, select(), configurations, user-defined flags, transitions, and so on.

We have enough experience to identify where current errors fall short. There are straightforward ways we make them clearer, more actionable, and more closely connected to relevant documentation.

I'm starting this for configuration-related errors since this is the Bazel area I know best. More broadly I'd like to extend these principles to Bazel error culture as a whole in the interest of making Bazel more accessible.

Crowd-sourced input on confusing messages welcome!

The text was updated successfully, but these errors were encountered:

gregestren · 2020-08-20T19:57:15Z

@jin

jin · 2020-08-20T22:38:55Z

/sub

Configuration IDs are long. Example: 401ac12588e4c9bbed7d8d880eded6fa015cc5c752cedb42fa0b1c177724bb76 This follows the spirit of Git commit hash prefixes to make cquery and "blaze config" smart enough to deduce full IDs from unambiguous prefixes. cquery now outputs short IDs and its config() function accepts them. "blaze config" outputs full IDs but accepts "$ blaze config <short ID>". Before: $ bazel cquery 'deps(//:foo)' //:foo (eabb6af2b39c468822f14aa928370856968c05a3936d5d90057948a5427c5892) //:bar (968c05a3936d5d9005798370856968b6af2b327c5898c050579487c5870f1504) After: $ bazel cquery 'deps(//:foo)' //:foo (eabb6af) //:bar (968c05a) $ bazel cquery 'config(//:foo, eab)' //:foo (eabb6af) Full IDs are computed at https://github.com/bazelbuild/bazel/blob/a9b118bbe1d7c6c4be4524547dddc1fc21ba60ad/src/main/java/com/google/devtools/build/lib/util/Fingerprint.java#L330. We could conceivably shorten them by using a SHA-1 hash. But that's still pretty long. And it's more consistent to hash all build entities the same way. Also beautified relevant errors for #11984. PiperOrigin-RevId: 330578952

No more need for a redundant config_setting. See bazelbuild#8583 for an example. This was a bit subtle. constraint_value can't directly export a ConfigMatchingProvider because it needs to know the platform to determine if it's a match. But platforms are built out of constraint_values, so the platform isn't available yet. So the parent target with the select() provides this detail. Also beautifies "invalid select() key" errors in support of bazelbuild#11984. Fixes bazelbuild#8583. RELNOTES[NEW]: select() directly supports constraint_value (no need for an intermediate config_setting). PiperOrigin-RevId: 327885099 Change-Id: Ifbdfa275ff83f0cb30207a5bd77aca317599fc21

No more need for a redundant config_setting. See #8583 for an example. This was a bit subtle. constraint_value can't directly export a ConfigMatchingProvider because it needs to know the platform to determine if it's a match. But platforms are built out of constraint_values, so the platform isn't available yet. So the parent target with the select() provides this detail. Also beautifies "invalid select() key" errors in support of #11984. Fixes #8583. RELNOTES[NEW]: select() directly supports constraint_value (no need for an intermediate config_setting). Closes #12071. PiperOrigin-RevId: 331181346

mobileink · 2020-10-05T19:45:59Z

If you're collecting error messages that need fixing, here's another one:

ERROR: <root>/src/BUILD.bazel:596:13: output 'src/refList.o' was not created
ERROR: <root>/src/BUILD.bazel:596:13: not all outputs were created or valid

This is not much better than "Your build failed". It will be totally opaque to users who do not know that "output" has special meaning for Bazel rules. It does not mean the compile failed; it might have failed, but it might have succeeded yet failed to put the output in the right place. Worst of all is "[not] created or valid" - doesn't Bazel know which?

Best,

Gregg

gregestren · 2020-10-05T20:16:40Z

Thanks, Gregg. Excellent and subtle point on the "A or B" phrasing. I'll dig in when I get a chance to see what options we have for those errors.

mobileink · 2020-10-08T12:48:14Z

Here's another useless error message:

ERROR: Failed to load Starlark extension '@bazel_skylib//lib:paths.bzl'.
Cycle in the workspace file detected. This indicates that a repository is used prior to being defined.
The following chain of repository dependencies lead to the missing definition.
 - @bazel_skylib
This could either mean you have to add the '@bazel_skylib' repository with a statement like `http_archive` in your WORKSPACE file (note that transitive dependencies are not added automatically), or move an existing definition earlier in your WORKSPACE file.
ERROR: cycles detected during target parsing

I have @bazel_skylib//lib:paths.bzl in a dozen files; which is it? Surely Bazel knows. I also have multiple workspaces. Bazel should be able to tell me where the problem is.

Gregg

In recent years, a frustrating error for Bazel users is the one caused by putting a reverse dependency rather than a package group into a target's visibility attribute. Such a mistake generally resulted in an error like this: ``` BUILD:7:10: in filegroup rule //pkg1:actual_target: cycle in dependency graph: //pkg1:actual_target //pkg1:dep_with_visibility .-> //pkg1:actual_target | //pkg1:dep_with_visibility `-- //pkg1:actual_target This cycle occurred because of a configuration option ``` This was confusing primarily because users don't think of visibility as causing a dependency—see, for instance, bazelbuild#11945. Additionally, the "This cycle occurred because of a configuration option" hint was not usually accurate or helpful. That the visibility mistake will be reported as a cycle is a fundamental property of how analysis is mapped onto Skyframe today, but a better hint was certainly possible. In fact, deep within Bazel's bowels there was already code to produce a better message, but it became mostly dormant during the analysis-loading interleaving work of 2017. This CL removes the "This cycle occurred because of a configuration option" hint completely and restores the old visibility hint when appropriate. The primary code change is to combine ConfiguredTargetCycleReporter and TransitiveTargetCycleReporter to form TargetCycleReporter. Now, a visibility cycle looks like this: ``` BUILD:2:10: in filegroup rule //pkg1:actual_target: cycle in dependency graph: //pkg1:actual_target //pkg1:dep_with_visibility .-> //pkg1:actual_target | //pkg1:dep_with_visibility `-- //pkg1:actual_target The cycle is caused by a visibility edge from //pkg1:dep_with_visibility to the non-package_group target //pkg1:actual_target. Note that visibility labels are supposed to be package_group targets, which prevents cycles of this form. ``` I humbly include this change in the bazelbuild#11984 program.

In recent years, a frustrating error for Bazel users is the one caused by putting a reverse dependency rather than a package group into a target's visibility attribute. Such a mistake generally resulted in an error like this: ``` BUILD:7:10: in filegroup rule //pkg1:actual_target: cycle in dependency graph: //pkg1:actual_target //pkg1:dep_with_visibility .-> //pkg1:actual_target | //pkg1:dep_with_visibility `-- //pkg1:actual_target This cycle occurred because of a configuration option ``` This was confusing primarily because users don't think of visibility as causing a dependency—see, for instance, #11945. Additionally, the "This cycle occurred because of a configuration option" hint was not usually accurate or helpful. That the visibility mistake will be reported as a cycle is a fundamental property of how analysis is mapped onto Skyframe today, but a better hint was certainly possible. In fact, deep within Bazel's bowels there was already code to produce a better message, but it became mostly dormant during the analysis-loading interleaving work of 2017. This CL removes the "This cycle occurred because of a configuration option" hint completely and restores the old visibility hint when appropriate. The primary code change is to combine ConfiguredTargetCycleReporter and TransitiveTargetCycleReporter to form TargetCycleReporter. Now, a visibility cycle looks like this: ``` BUILD:2:10: in filegroup rule //pkg1:actual_target: cycle in dependency graph: //pkg1:actual_target //pkg1:dep_with_visibility .-> //pkg1:actual_target | //pkg1:dep_with_visibility `-- //pkg1:actual_target The cycle is caused by a visibility edge from //pkg1:dep_with_visibility to the non-package_group target //pkg1:actual_target. Note that visibility labels are supposed to be package_group targets, which prevents cycles of this form. ``` I humbly include this change in the #11984 program. Closes #12272. PiperOrigin-RevId: 342638902

This is a common user problem: users see this error and don't understand what it means or how to diagnose. This change is an opening salvo in a broader plan to integrate more "beautiful" error messaging into Blaze, inspired by https://bazel.build/designs/2016/05/23/beautiful-error-messages.html Example: config_setting( name = "foo", values = {"cpu": "not_a_valid_cpu}, ) config_setting( name = "foo2", values = {"cpu": "also_not_a_valid_cpu"}, ) cc_binary( name = "cc", srcs = select({ ":foo": [], ":foo2": [], })) $ blaze build //testapp:cc Before: ----------- ERROR: /workspace/testapp/BUILD:16:10: Configurable attribute "srcs" doesn't match this configuration (would a default condition help?). Conditions checked: //testapp:foo //testapp:foo2 After: ----------- ERROR: /workspace/BUILD:16:10: configurable attribute "srcs" in //testapp:cc doesn't match this configuration. Would a default condition help? Conditions checked: //testapp:foo //testapp:foo2 //testapp:foo3 To see a condition's definition, run: bazel query --output=build <condition label>. This instance of //testapp:cc has configuration identifier 7f2b080. To inspect its configuration, run: bazel config 7f2b080. For more help, see https://docs.bazel.build/configurable-attributes.html#why-doesnt-my-select-choose-what-i-expect. Themes: ----------- - This is consciously longer and more verbose. The primary goal is *clarity*, which is not always aligned with shortness. This includes paragraph-style line spacing to de-densify potentially overwhelming content. - Uses casual but personable language, including actionable phrasing ("see", "run") to help guide understanding and diagnostics. - Provides a thorough walkthrough including proposed next steps for the immediate problem while leaving discussion on broader concepts to outside links. - Increases our commitment to "always supported URLs" (including in-page anchors!) - Main idea is to look like the cleanest, most helpful Stackoverflow-style answer possible. There's no intrinsic reason why internal messaging can't be held to the same accessibility standards. For #11984. PiperOrigin-RevId: 369470807

gregestren · 2021-04-20T18:38:29Z

@mobileink - I just submitted 3d33d7b and looking for another error to polish.

For #11984 (comment), could you sketch your version of the ideal message? In 3d33d7b 's description I laid out principles I'm trying to introduce: basically make error messages look like great StackOverflow answers (clear, helpful, readable, concise).

Re: implementation, I'm not sure how much of the relevant context the code at that stage has. That error is generated at

bazel/src/main/java/com/google/devtools/build/lib/skyframe/SkyframeActionExecutor.java

Line 1599 in a790c17

action.getOwner().getLocation(), prefix + "was not created" + suffix));

and

bazel/src/main/java/com/google/devtools/build/lib/skyframe/SkyframeActionExecutor.java

Line 1194 in a790c17

"not all outputs were created or valid",

catskul · 2021-12-16T19:09:34Z

Here's one that's not confusing exactly, but just hard to read and easy to misread. Keep in mind that I shortened the paths to make the example simpler, but its even harder to read with real-world path and target lengths

ERROR: /home/catskul/repos/abc/red/RedInfManager/tests/BUILD:83:8: in cc_test rule //red/RedInfManager/tests:MTRConfigTest: target '//red/Tasks/Inf:RedInfTaskConfig' is not visible
from target '//red/RedInfManager/tests:MTRConfigTest'. Check the visibility declaration of the former target if you think the dependency is legitimate

Would be much more readable as:

ERROR: 
    /home/catskul/repos/abc/red/RedInfManager/tests/BUILD:83:8: 
        in cc_test rule //red/RedInfManager/tests:MTRConfigTest: 
                target '//red/Tasks/Inf:RedInfTaskConfig' 
            is not visible from 
                target '//red/RedInfManager/tests:MTRConfigTest'. 
    Check the visibility declaration of the former target if you think the dependency is legitimate

gregestren · 2021-12-17T00:28:57Z

This is great. Thanks for the suggestion @catskul.

Some basic formatting standards could go a long way.

This is a common user problem: users see this error and don't understand what it means or how to diagnose. This change is an opening salvo in a broader plan to integrate more "beautiful" error messaging into Blaze, inspired by https://bazel.build/designs/2016/05/23/beautiful-error-messages.html Example: config_setting( name = "foo", values = {"cpu": "not_a_valid_cpu}, ) config_setting( name = "foo2", values = {"cpu": "also_not_a_valid_cpu"}, ) cc_binary( name = "cc", srcs = select({ ":foo": [], ":foo2": [], })) $ blaze build //testapp:cc Before: ----------- ERROR: /workspace/testapp/BUILD:16:10: Configurable attribute "srcs" doesn't match this configuration (would a default condition help?). Conditions checked: //testapp:foo //testapp:foo2 After: ----------- ERROR: /workspace/BUILD:16:10: configurable attribute "srcs" in //testapp:cc doesn't match this configuration. Would a default condition help? Conditions checked: //testapp:foo //testapp:foo2 //testapp:foo3 To see a condition's definition, run: bazel query --output=build <condition label>. This instance of //testapp:cc has configuration identifier 7f2b080. To inspect its configuration, run: bazel config 7f2b080. For more help, see https://docs.bazel.build/configurable-attributes.html#why-doesnt-my-select-choose-what-i-expect. Themes: ----------- - This is consciously longer and more verbose. The primary goal is *clarity*, which is not always aligned with shortness. This includes paragraph-style line spacing to de-densify potentially overwhelming content. - Uses casual but personable language, including actionable phrasing ("see", "run") to help guide understanding and diagnostics. - Provides a thorough walkthrough including proposed next steps for the immediate problem while leaving discussion on broader concepts to outside links. - Increases our commitment to "always supported URLs" (including in-page anchors!) - Main idea is to look like the cleanest, most helpful Stackoverflow-style answer possible. There's no intrinsic reason why internal messaging can't be held to the same accessibility standards. For bazelbuild/bazel#11984. PiperOrigin-RevId: 369470807

bcsgh · 2023-12-23T21:00:50Z

@gregestren regarding the "was not created" error message, what would improve things the most for me would be some help for cases where the action, worked and the expected file was generated, just with the wrong name or in the wrong location. I've on more occasions than I care to count stuffed postfix_script = "find . >&2 && false", into an external build rule just to try to figure out what it actually did.

Just a working directory listing (or a listing of new files that the action created) would be an improvement. If that's too verbose, then dump that to a file and tell me where it is. For bonus points; pick the 3-10 closes "matches" and ask "did you want...".

"Nothing is a failure if you learn something you then use use to make the next attempt better."

In this case, while I learn something from the default message, there is nothing I can do with it to make the next attempt better.

gregestren · 2024-01-04T21:10:54Z

@bcsgh good points. Are you talking about a case where Bazel knows where the output is written and isn't telling the user?

i.e. if you write a genrule cmd` that writes to some arbitrary path, Bazel doesn't necessarily know what's written where. We might be able to query the working directory. But that might require more cooperation with the file system, remote executor service, etc.

bcsgh · 2024-01-04T21:25:59Z

I'm thinking of the cast where bazel has no clue what went wrong, only that no result ended up in the expected location.

I'm not expecting bazel to log file access or anything but just give me some actionable information about the final state. Something as simple as find from the rule's cwd would be nice. Even just dumping a path where I can do that from on my own would be an improvement. (Does bazel delete those directories on failure? I don't ever remember being able to locate them after the fact unless things worked.)

gregestren · 2024-01-04T21:39:14Z

You're doing local builds (no remote executor)?

Have you tried $ bazel build //foo -s?

bcsgh · 2024-01-04T21:58:28Z

I've tried --subcommands a few times, but IIRC I was never able to find the working directory from failed build steps listed in there. Even if it is, it's too verbose to be a practical solution to the problem here.

While I'd like to see at a minimum is the existing error message:

output 'src/refList.o' was not created

Becomes something like

output 'src/refList.o' was not created in directory /some/path/to/steps/working/dir

Where find /some/path/to/steps/working/dir -type f has a good chance of giving me something useful.

gregestren added P1 I'll work on this now. (Assignee required) team-Configurability platforms, toolchains, cquery, select(), config transitions type: documentation (cleanup) labels Aug 20, 2020

This was referenced Aug 20, 2020

Useless "Analysis failed" message #11974

Open

Improve configurability documentation #11967

Open

gregestren mentioned this issue Sep 9, 2020

Support constraint_value directly in select() #12071

Closed

benjaminp mentioned this issue Oct 15, 2020

Restore target cycle errors to their former grandeur. #12272

Closed

gregestren added P2 We'll consider working on this in future. (Assignee optional) and removed P1 I'll work on this now. (Assignee required) labels Dec 9, 2020

fmeum mentioned this issue Oct 30, 2022

WIP: Make visibility errors more readable #16608

Draft

keertk added the team-Documentation Documentation improvements that cannot be directly linked to other team labels label Jan 10, 2023

gregestren mentioned this issue Feb 15, 2023

Improve Errors for Transitive Rules #15791

Open

gregestren mentioned this issue Dec 27, 2024

Error reporting for select-based target_compatible_with expressions is too vague #22850

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Beautify Bazel configuration errors #11984

Beautify Bazel configuration errors #11984

gregestren commented Aug 20, 2020 •

edited

Loading

gregestren commented Aug 20, 2020

jin commented Aug 20, 2020

mobileink commented Oct 5, 2020

gregestren commented Oct 5, 2020

mobileink commented Oct 8, 2020

gregestren commented Apr 20, 2021 •

edited

Loading

catskul commented Dec 16, 2021 •

edited

Loading

gregestren commented Dec 17, 2021

bcsgh commented Dec 23, 2023

gregestren commented Jan 4, 2024

bcsgh commented Jan 4, 2024

gregestren commented Jan 4, 2024

bcsgh commented Jan 4, 2024

Beautify Bazel configuration errors #11984

Beautify Bazel configuration errors #11984

Comments

gregestren commented Aug 20, 2020 • edited Loading

gregestren commented Aug 20, 2020

jin commented Aug 20, 2020

mobileink commented Oct 5, 2020

gregestren commented Oct 5, 2020

mobileink commented Oct 8, 2020

gregestren commented Apr 20, 2021 • edited Loading

catskul commented Dec 16, 2021 • edited Loading

gregestren commented Dec 17, 2021

bcsgh commented Dec 23, 2023

gregestren commented Jan 4, 2024

bcsgh commented Jan 4, 2024

gregestren commented Jan 4, 2024

bcsgh commented Jan 4, 2024

gregestren commented Aug 20, 2020 •

edited

Loading

gregestren commented Apr 20, 2021 •

edited

Loading

catskul commented Dec 16, 2021 •

edited

Loading