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.parse_with_errorformat​

def ActionErrorCtx.parse_with_errorformat(
*,
category: str,
error: str,
errorformats: list[str] | tuple[str, ...],
) -> list[ActionSubError]

Parse error text using vim errorformat patterns to create structured error information. This method leverages vim's proven errorformat system to extract file paths, line numbers, and error messages from compiler/tool output, automatically creating ActionSubError objects.

For errorformat pattern syntax, see: https://neovim.io/doc/user/quickfix.html#errorformat

Multiple patterns can be provided and will be tried in order until one matches. This is useful for tools that may output errors in different formats.

Args:

  • category: Base category name for the generated sub-errors (e.g., "rust", "gcc")
  • error: The error text to parse (typically stderr or stdout from the failed action)
  • errorformats: List of vim errorformat pattern strings to try matching against

Returns a list of ActionSubError objects with structured error information including file locations when successfully parsed from the error text.

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.