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.
"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.
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.
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.
Similarly to rlang_backtrace_on_error_report, you can set
rlang_backtrace_on_warning_report inside RMarkdown documents to
tweak the display of warnings. This is useful in conjunction with
global_entrace(). Because of technical limitations, there is
currently no corresponding rlang_backtrace_on_warning option for
normal R sessions.
To get full entracing in an Rmd document, include this in a setup chunk before the first error or warning is signalled.
```{r setup}
rlang::global_entrace()
options(rlang_backtrace_on_warning_report = "full")
options(rlang_backtrace_on_error_report = "full")
```
rlang_backtrace_on_warning
# Display a simplified backtrace on error for both base and rlang
# errors:
# options(
# rlang_backtrace_on_error = "branch",
# error = rlang::entrace
# )
# stop("foo")
Run the code above in your browser using DataLab