Backtracing R Code for Troubleshooting

Published

May 21, 2026

Abstract

How to use rlang backtraces to identify where errors occur in R code

Description

A backtrace shows the full call stack at the point an R error occurs, so you can identify which function call produced it.

Including a backtrace when you submit a support ticket gives the support team the diagnostic context they need to find the cause.

Solution

If the rlang package is not already installed, install it from the R console:

R Console

install.packages("rlang")

To capture a backtrace, run the following two lines in the R console.

R Console

rlang::global_entrace()
options(rlang_backtrace_on_error = "full")

These commands only produce output when your code raises an error, and must be run before the code that produces the error.

Note

These settings apply only to the current R session. To make them persist across sessions, add them to an R startup file. See What They Forgot to Teach You About R for guidance on configuring .Rprofile.

For example, fitting a linear model that references a column not present in the data produces a backtrace like this:

R Console

> rlang::global_entrace()
> options(rlang_backtrace_on_error = "full")

> lm(y ~ x , data = mtcars)
Error:
! object 'y' not found
Backtrace:
    ▆
 1. ├─stats::lm(y ~ x, data = mtcars)
 2. │ └─base::eval(mf, parent.frame())
 3. │   └─base::eval(mf, parent.frame())
 4. ├─stats::model.frame(formula = y ~ x, data = mtcars, drop.unused.levels = TRUE)
 5. └─stats::model.frame.default(formula = y ~ x, data = mtcars, drop.unused.levels = TRUE)
 6.   └─base::eval(predvars, data, env)
 7.     └─base::eval(predvars, data, env)

The numbered call stack traces which function calls led to the error. Include this output when you submit a support ticket so the support team has the context needed to diagnose the issue.

If you’re still having issues, you can reach out to Support by opening a ticket.