Build Report

The build report is a JSON file that you can ask buck to output which contains structured information about the result of your build. It is particularly valuable for its reporting of unsuccessful outcomes in addition to successful ones; usually, most use cases that only need to care about successful outcomes are well served by direct usage of the CLI.

To request a build report, pass --build-report <path> to buck build on the CLI.

At a high level, the build report outputs information for each of the targets that you requested to have built on the CLI. As a result, it may report information for more than one configuration or subtarget of a target. For example, this can happen if you passed --target-platforms or built :target and :target[sub].

Schema

BuildReport {
    # A unique ID identifying this buck invocation. Currently a UUID, however
    # that may change in the future.
    trace_id: str,

    # True if all requested targets built successfully
    success: bool,

    # The absolute path to the project root
    project_root: Path,

    # The results of the build, categorized by unconfigured target
    results: dict[TargetLabel, BuildReportEntry],

    # A cache for error message lookup. This is meant for deduplicating strings
    # that might otherwise appear many times in the build report and cause an
    # unnecessary size increase. They keys are used in other fields in the build
    # report in reference to these strings.
    strings: dict[str, str],

    # BUCK1 BACKCOMPAT ONLY!
    #
    # Currently always empty. Will be filled in if a flag is passed in the future.
    #
    # A map from targets that failed to build to error messages describing the
    # failure.
    failures: dict[TargetLabel, str],
}

BuildReportEntry {
    # The results of building the target in the given configurations
    configured: dict[Configuration, ConfiguredBuildReportEntry],

    # Errors encountered while building this target.
    #
    # Note that this does not include the errors that are found within the
    # `ConfiguredBuildReportEntry`s. Instead, it includes additional errors
    # which could not be associated with a specific configuration of the
    # target, typically because they occurred before the target could be
    # configured.
    errors: list[Error],

    # BUCK1 BACKCOMPAT ONLY!
    #
    # The two fields below are included for buck1 backwards compatibility only.
    # They are both computed by aggregating across all the configured targets in
    # the way you might expect.
    success: "FAIL" | "SUCCESS,
    outputs: dict[str, list[Path]],

    # The path to the package containing this target, relative to the project
    # root. This is the source code location for this target.
    package_project_relative_path: Optional[str]
}

ConfiguredBuildReportEntry {
    # Did this target build successfully or not?
    success: "FAIL" | "SUCCESS,

    # A map of subtargets that were built to a list of the successfully built
    # outputs for that subtarget.
    #
    # The keys are generated by joining the subtargets with a `|`. For example,
    # if you request to have `:target` and `:target[foo][bar]` built on the CLI,
    # this list will contain one entry for `""` and one for `"foo|bar"`.
    outputs: dict[str, list[Path]],

    # The number of targets in the configured dependency graph of this target.
    #
    # This is only included if `-c buck2.log_configured_graph_size=true` is set.
    # Otherwise, it is left as None.
    configured_graph_size: Optional[uint],
}

Error {
    # The stringified hash of the same stringified error message that is shown to the user on the
    # console. The hash is stored as the key in the `strings` cache of the `BuildReport`
    message_content: str,

    # Structured action error. Present only if the error was actually an action error
    action_error: Optional[ActionError],

    # An index that can be used to detect duplicate errors. Two errors with the
    # same cause index have the same cause. Note that that does not mean that
    # they have the same error message.
    cause_index: uint,
}

ActionError {
    # The action key
    key: ActionKey,

    # The action name
    name: ActionName,

    # Digest of the action
    digest: str,

    # Stringified hash of the stderr of the action
    stderr: str,

    # Stringified hash of the stdout of the action
    stdout: str,

    # Stringified hash of the same stringified error message that is provided by the action
    error: str,

    # Optional list of error categorizations provided by an error handler which is invoked
    # in the event of a failed action, or an error message if the error handler failed.
    error_diagnostics: Optional[ActionErrorDiagnostics],
}

ActionKey {
    # The configured target, anon target, or bxl function which owns this action
    owner: str,
}

ActionName {
    # The category of the action
    category: str,

    # The optional identifier of the action
    identifier: Optional[str],
}

enum ActionErrorDiagnostics {
    # The list of sub errors if the error handler succeeded
    sub_errors: list[ActionSubError],

    # The stringified hash of the error message if the error handler failed
    handler_invocation_error: String,
}

ActionSubError {
    # Name of the error category. The category should be finer grain error categorizations
    # provided by the rule authors, and tend to be language specific. These should not be
    # any kind of shared concepts among all errors for all languages/rules. For example,
    # timeouts and infra errors should not go here - buck2 tries to categorize these types
    # of errors automatically. An example of a finer grain error category may be the error
    # code for rustc outputs.
    category: str,

    # The stringified hash of the extra message provided for the specific sub-error category.
    message_content: str,

    # List of error locations, if any
    locations: Optional[list[ActionErrorLocation]],
}

ActionErrorLocation {
    # File path where the error appeared, preferrably either project-relative or absolute.
    file: str,

    # Optional line number
    line: Optional[u64]
}

On Compatibility

The format of the build report is generally stable. However, note that new fields may be added at any time, and you should ensure this does not cause your parsing to fail.

A number of fields above are marked as being for buck1 backwards compatibility only. These fields all have superior alternatives available in the build report already. We would strongly prefer that new code neither use nor parse them, as this increases the likelyhood that they can be removed one day.

The build report additionally outputs a few fields that are intentionally not documented here. Those fields are even less useful than ones documented as being for backwards compatibility only, and even closer to removal. Please avoid using or parsing these if at all possible.

Limitations

The build report currently has at least the following limitations:

1. It includes only one action error per failed target. This is the expected behavior when --keep-going is not passed, but when --keep-going is passed, this is a bug.
2. It is currently not generated when a non-existant package is specified on the command line. This is also a bug.
3. It cannot be requested for any buck2 command other than build
4. Errors do not contain any additional metadata outside of the error message. This will be made available as such metadata is available in buck2.
5. The "failures" field is always empty. This will be changed under a backcompat opt-in flag in the future.

Finally, it's worth raising that the concept of error deduplication has some fundamental limitations; if two targets both refer to the same non-existant dependency, do those errors have the same cause (the dependency doesn't exist) or different causes (each target is individually broken)? As a result, the exact details of when two errors are considered to have the same cause are not generally stable, and may not always be what you expect.