R: Display backtrace on error

rlang_backtrace_on_error {rlang} | R Documentation

## Display backtrace on error

### Description

rlang errors carry a backtrace that can be inspected by calling `last_error()`. You can also control the default display of the backtrace by setting the option `rlang_backtrace_on_error` to one of the following values:

- `"none"` show nothing.

- `"reminder"`, the default in interactive sessions, displays a reminder that you can see the backtrace with `last_error()`.

- `"branch"` displays a simplified backtrace.

- `"collapse"` displays a collapsed backtrace tree.

- `"full"`, the default in non-interactive sessions, displays the full tree.

rlang errors are normally thrown with `abort()`. If you promote base errors to rlang errors with `global_entrace()`, `rlang_backtrace_on_error` applies to all errors.

### Promote base errors to rlang errors

You can use `options(error = rlang::entrace)` to promote base errors to rlang errors. This does two things:

- It saves the base error as an rlang object so you can call `last_error()` to print the backtrace or inspect its data.

- It prints the backtrace for the current error according to the `rlang_backtrace_on_error` option.

### Errors in RMarkdown

The display of errors depends on whether they're expected (i.e. chunk option `error = TRUE`) or unexpected:

- Expected errors are controlled by the global option `"rlang_backtrace_on_error_report"` (note the `_report` suffix). The default is `"none"` so that your expected errors don't include a reminder to run `rlang::last_error()`. Customise this option if you want to demonstrate what the error backtrace will look like.

  You can also use `last_error()` to display the trace like you would in your session, but it currently only works in the next chunk.

- Unexpected errors are controlled by the global option `"rlang_backtrace_on_error"`. The default is `"branch"` so you'll see a simplified backtrace in the knitr output to help you figure out what went wrong.

When knitr is running (as determined by the `knitr.in.progress` global option), the default top environment for backtraces is set to the chunk environment `knitr::knit_global()`. This ensures that the part of the call stack belonging to knitr does not end up in backtraces. If needed, you can override this by setting the `rlang_trace_top_env` global option.

### Examples

    # Display a simplified backtrace on error for both base and rlang
    # errors:

    # options(
    #   rlang_backtrace_on_error = "branch",
    #   error = rlang::entrace
    # )
    # stop("foo")

[Package rlang version 1.0.2 Index]