Skip to main content

ActionErrorCtx

Methods available on ActionErrorCtx to help categorize the action failure. These categorizations should be finer grain, and most likely language specific.

ActionErrorCtx.new_error_location​

def ActionErrorCtx.new_error_location(
*,
file: str,
line: None | int = None,
) -> ActionErrorLocation

Create a new error location, specifying a file path and an optional line number.

The file path should be either a project-relative path, or an absolute path.

ActionErrorCtx.new_sub_error​

def ActionErrorCtx.new_sub_error(
*,
category: str,
message: None | str = None,
locations: None | list[ActionErrorLocation] | tuple[ActionErrorLocation, ...] = None,
) -> ActionSubError

Create a new sub error, specifying an error category name, optional message, and an optional list of error locations.

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': Required, useful for providing a more granular error category for action errors. 'message': Optional, provide users with additional context about the error to help with debugging/understandability/resolution, etc. 'locations': Optional, file path and line number of the error location, useful for external integration to highlight where the error is.

The message will be emitted to the build report, and to the stderr in the error diagnostics section.

ActionErrorCtx.output_artifacts​

ActionErrorCtx.output_artifacts: dict[Artifact, ArtifactValue]

Allows the output artifacts to be retrieve if outputs_for_error_handler is set and the output artifact exists. This is useful for languages with structured error output, making the error retrieval process simpler.

This is also the recommended way to retrieve file path and line number, as reliably extracting that information from stdout/stderr can be challenging

ActionErrorCtx.stderr​

ActionErrorCtx.stderr: str

Retrieve the stderr of the failed action. Can use string/regex matching to identify the error in order to categorize it.

ActionErrorCtx.stdout​

ActionErrorCtx.stdout: str

Retrieve the stdout of the failed action. Can use string/regex matching to identify the patterns in order to categorize it.