Skip to main content

Debugging with reprex() and browser()

r
Some good practices and useful tools to debug R code.
Authors

Etienne Bacher

Niklas Hohmann

Published

November 16, 2026

View source file

install.packages(c("palaeoverse", "reprex"))

Objectives

  • Learn the essential steps to debug R code
  • Learn how to use the package reprex to create a small reproducible example
  • Learn how to use specific debugging tools such as browser() and breakpoints

Introduction

Knowing how to debug code is an essential skill, whether one writes an analysis for a paper or develops an R package. This module covers several tools that aim to make the debugging process easier.

The following code is taken from the “Latitudinal trends in Phanerozoic reefs” vignette, but let’s pretend we have written this code from scratch:

library(palaeoverse)

data(reefs)
reef_counts <- group_apply(occdf = reefs, group = "interval", fun = nrow)
# Assign a common time scale based on an interval key
reefs <- look_up(occdf = reefs,
                 early_interval = "interval",
                 late_interval = "interval",
                 int_key = interval_key)
reefs <- subset(reefs, interval_max_ma <= 541)
# Extract Phanerozoic stage-level stages for time bins
bins <- time_bins(interval = "Phanerozoic", rank = "stage")

bin_time(occdf = reefs, bins = bins, method = "mid")
Error in `[.data.frame`:
! undefined columns selected

We now have an error caused by bin_time(). The first thing we can do is run traceback() to see which call inside bin_time() caused the error:

> traceback()
4: stop("undefined columns selected")
3: `[.data.frame`(occdf, , max_ma, drop = TRUE)
2: occdf[, max_ma, drop = TRUE]
1: bin_time(occdf = reefs, bins = bins, method = "mid") at #1

The trace can be read bottom-up: bin_time() failed because of the line occdf[, max_ma, drop = TRUE], which itself failed because of a wrong use of [.

This helps, but the root cause still isn’t very clear. Therefore, we’ll have to do some debugging.

Reducing the problem

The longer the code you try to debug, the more potential causes you have to explore. The first thing to do when you can’t find the bug in your code right away is to build a minimal reproducible example, aka a reprex (this is also known as a MRE, for “Minimal Reproducible Example”). This helps isolate the problem and makes it easier to communicate it to other users and maintainers.

In our example above, we can reduce the problem in two ways: we can reduce the data first, and then reduce the code.

Reduce the size of the data

In the debugging process, we will likely run the code at least a handful of times. Therefore, we want to make sure that it runs as fast as possible so that we don’t lose our focus. The easiest way to do this is to reduce the size of our input data.

In addition to making the error appear faster, it is also easier to compare the actual and expected outputs when the data is as small and simple as possible.

In this example, the dataset we are using has thousands of rows and 14 columns:

data(reefs)
dim(reefs)
[1] 4363   14

Let’s try to reduce the size of our data:

# Select the first rows of the data
reefs2 <- head(reefs)

reef_counts <- group_apply(occdf = reefs2, group = "interval", fun = nrow)
# Assign a common time scale based on an interval key
reefs2 <- look_up(occdf = reefs2,
                 early_interval = "interval",
                 late_interval = "interval",
                 int_key = interval_key)
reefs2 <- subset(reefs2, interval_max_ma <= 541)
# Extract Phanerozoic stage-level stages for time bins
bins <- time_bins(interval = "Phanerozoic", rank = "stage")

bin_time(occdf = reefs2, bins = bins, method = "mid")
Error in `[.data.frame`:
! undefined columns selected

We still see the same error but now we only have 6 rows left (the default provided by head()), much better! Let’s try to reduce that to one row and to remove some columns.

reefs2 <- head(reefs, n = 1)
reefs2 <- reefs2[, 1:5]

reef_counts <- group_apply(occdf = reefs2, group = "interval", fun = nrow)
Error in `group_apply()`:
! Supplied `group` is not a named column in `occdf`
# Assign a common time scale based on an interval key
reefs2 <- look_up(occdf = reefs2,
                 early_interval = "interval",
                 late_interval = "interval",
                 int_key = interval_key)
Error in `look_up()`:
! `early_interval` needs to match a column name of `occdf`
reefs2 <- subset(reefs2, interval_max_ma <= 541)
Error:
! object 'interval_max_ma' not found
# Extract Phanerozoic stage-level stages for time bins
bins <- time_bins(interval = "Phanerozoic", rank = "stage")

bin_time(occdf = reefs2, bins = bins, method = "mid")
Error in `[.data.frame`:
! undefined columns selected

Hmm, we don’t have the same error anymore, so we removed too many columns. Let’s try to keep 6 instead of 5:

reefs2 <- head(reefs, n = 1)
reefs2 <- reefs2[, 1:6]

reef_counts <- group_apply(occdf = reefs2, group = "interval", fun = nrow)
# Assign a common time scale based on an interval key
reefs2 <- look_up(occdf = reefs2,
                 early_interval = "interval",
                 late_interval = "interval",
                 int_key = interval_key)
reefs2 <- subset(reefs2, interval_max_ma <= 541)
# Extract Phanerozoic stage-level stages for time bins
bins <- time_bins(interval = "Phanerozoic", rank = "stage")

bin_time(occdf = reefs2, bins = bins, method = "mid")
Error in `[.data.frame`:
! undefined columns selected

Bingo! We have the same error as before, but now we only have one row and six columns.

NoteI can’t reduce the size of my data

Here, we were lucky enough that we could drastically reduce the size of the data used. This is not always the case. Maybe the error you are experiencing only appears with large data, in which case you don’t have many options.

Trying to reduce the size of the data is important, no matter what: knowing that the error only appears with large data is key information and might help debug your code.

Let’s now try to reduce the size of the code.

Reduce the size of the code

This is an important process: we want to remove as much code as possible to lower the number of potential causes leading to the error.

Starting from this:

reefs2 <- head(reefs, n = 1)
reefs2 <- reefs2[, 1:6]

reef_counts <- group_apply(occdf = reefs2, group = "interval", fun = nrow)
# Assign a common time scale based on an interval key
reefs2 <- look_up(occdf = reefs2,
                 early_interval = "interval",
                 late_interval = "interval",
                 int_key = interval_key)
reefs2 <- subset(reefs2, interval_max_ma <= 541)
# Extract Phanerozoic stage-level stages for time bins
bins <- time_bins(interval = "Phanerozoic", rank = "stage")

bin_time(occdf = reefs2, bins = bins, method = "mid")
Error in `[.data.frame`:
! undefined columns selected

We see that reef_counts is defined but never actually used, so this cannot be the root cause. Let’s remove it.

The subset() call is also suspicious: now that he have only one row left in our test data, does this subset() actually do anything?

reefs2 <- head(reefs, n = 1)
reefs2 <- reefs2[, 1:6]

reefs2 <- look_up(occdf = reefs2,
                 early_interval = "interval",
                 late_interval = "interval",
                 int_key = interval_key)

identical(reefs2, subset(reefs2, interval_max_ma <= 541))
[1] TRUE

It doesn’t affect reefs2, so let’s remove it as well.

We now have this:

reefs2 <- head(reefs, n = 1)
reefs2 <- reefs2[, 1:6]

reefs2 <- look_up(occdf = reefs2,
                 early_interval = "interval",
                 late_interval = "interval",
                 int_key = interval_key)
bins <- time_bins(interval = "Phanerozoic", rank = "stage")

bin_time(occdf = reefs2, bins = bins, method = "mid")
Error in `[.data.frame`:
! undefined columns selected

We have removed two out of five function calls, not bad. We still don’t really understand the cause though.

Let’s assume that the documentation also doesn’t give any hint about this error message. If we are completely stuck, then we may want to ask other people, such as package maintainers on GitHub or people on StackOverflow. We have done our best to reduce the size of the problem, making it easier for other people to help us.

Still, we need to ensure that our reprex is correctly made and we must find a nice way to share it, e.g., as an issue on GitHub or with other users.

How to ensure that your reprex actually is a reprex

It seems like we have done everything we can to make the problem easier to reproduce, even for other people (e.g. package developers). However, there is one thing that still needs to be cleaned: our environment.

Our environment may have tons of variables, datasets, and options that were defined before but are not relevant to our problem. Some of those objects may interact in some way with our problematic code, meaning that we need to clean our environment to ensure that we can correctly reproduce the issue.

One way to do this is to restart the R session, but this can easily be forgotten. A more robust solution is to use the package reprex. This package provides a function called reprex() in which we can put all of the code related to our problem. reprex() will start a separate R session in the background to run this code and then report its results. Since this is a completely separate R session, it will error if our code isn’t completely self-contained, and this would indicate that our reproducible example isn’t actually… reproducible.

This is extremely useful to solve the problem yourself, but it is even more useful when reporting a bug to colleagues and package developers: if your example runs in reprex(), then it is almost guaranteed that it can be easily reproduced by other people with different environments.

reprex::reprex({
  reefs2 <- head(reefs, n = 1)
  reefs2 <- reefs2[, 1:6]

  reefs2 <- look_up(occdf = reefs2,
                  early_interval = "interval",
                  late_interval = "interval",
                  int_key = interval_key)
  bins <- time_bins(interval = "Phanerozoic", rank = "stage")

  bin_time(occdf = reefs2, bins = bins, method = "mid")
})
reefs2 <- head(reefs, n = 1)
#> Error:
#> ! object 'reefs' not found
reefs2 <- reefs2[, 1:6]
#> Error:
#> ! object 'reefs2' not found

reefs2 <- look_up(occdf = reefs2,
                early_interval = "interval",
                late_interval = "interval",
                int_key = interval_key)
#> Error in `look_up()`:
#> ! could not find function "look_up"
bins <- time_bins(interval = "Phanerozoic", rank = "stage")
#> Error in `time_bins()`:
#> ! could not find function "time_bins"

bin_time(occdf = reefs2, bins = bins, method = "mid")
#> Error in `bin_time()`:
#> ! could not find function "bin_time"

Our reprex fails, but not with the error we experienced so far! We forgot to add the calls to library() and data(), which is the reason R could not find the functions and data provided by the palaeoverse package.

reprex::reprex({
  library(palaeoverse)
  data(reefs)
  reefs2 <- head(reefs, n = 1)
  reefs2 <- reefs2[, 1:6]

  reefs2 <- look_up(occdf = reefs2,
                  early_interval = "interval",
                  late_interval = "interval",
                  int_key = interval_key)
  bins <- time_bins(interval = "Phanerozoic", rank = "stage")

  bin_time(occdf = reefs2, bins = bins, method = "mid")
})
library(palaeoverse)
data(reefs)
reefs2 <- head(reefs, n = 1)
reefs2 <- reefs2[, 1:6]

reefs2 <- look_up(occdf = reefs2,
                early_interval = "interval",
                late_interval = "interval",
                int_key = interval_key)
bins <- time_bins(interval = "Phanerozoic", rank = "stage")

bin_time(occdf = reefs2, bins = bins, method = "mid")
#> Error in `[.data.frame`:
#> ! undefined columns selected

This is the situation we have so far, so we can now share this output with other people and they should be able to reproduce the issue.

Note that it is good practice to show more information on our session, including the version of packages used. This can be done with the argument session_info in reprex():

reprex::reprex({
  library(palaeoverse)
  data(reefs)
  reefs2 <- head(reefs, n = 1)
  reefs2 <- reefs2[, 1:6]

  reefs2 <- look_up(occdf = reefs2,
                  early_interval = "interval",
                  late_interval = "interval",
                  int_key = interval_key)
  bins <- time_bins(interval = "Phanerozoic", rank = "stage")

  bin_time(occdf = reefs2, bins = bins, method = "mid")
}, session_info = TRUE)

You now know how to use reprex()! Note that the steps before actually using it are key: very often, other people will ask you to minimize your issue as much as possible before reporting it. In many cases, you can also find the issue on your own just by reducing it.

Debugging a function

Debugging a function that you wrote (either in a package or as part of a project) can be annoying because an entire (internal) block of code gets executed and you only see the final error.

One solution is to put various print() statements in the function body to see which ones get evaluated (meaning that the code has run fine so far) and which ones don’t because the function errored before.

However, a more robust and convenient approach is to use a function that will stop the evaluation and put us in the evaluating environment: browser(). This allows us to run line by line in the function body, and it is therefore a key tool when you start writing your own functions.

We will use issue #280 in palaeoverse as an example throughout this section.

browser()

The bug report above gives a reprex to reproduce the error (note that at the time you are reading this, this bug has already been fixed):

library(palaeoverse)

occdf <- reefs[1:5, ]
bin_space(occdf = occdf, spacing = 1000, sub_grid = 250, return = TRUE)
Error in `bin_space()`:
! object 'secondary' not found

The error happens in bin_space(), which is a long function:

palaeoverse::bin_space
#> function (occdf, lng = "lng", lat = "lat", spacing = 100, sub_grid = NULL, 
#>     return = FALSE, plot = FALSE) 
#> {
#>     if (!is.data.frame(occdf)) {
#>         stop("occdf should be of class dataframe")
#>     }
#>    
#>    [ MANUALLY TRUNCATED ]
#>   
#> }

One approach to narrow down the cause of the error would be to add multiple print() statements, so that we can check which messages are printed (indicating that the code ran without error) and which are not because the error occurred before reaching them.

However, it would be way more convenient to be able to execute the internal code line by line so that we can see precisely which line errors. This is the objective of browser(). We can start by putting a browser() at the top, re-loading the function, and executing it again:

function (occdf, lng = "lng", lat = "lat", spacing = 100, sub_grid = NULL, 
    return = FALSE, plot = FALSE) 
{
+   browser()  
    if (!is.data.frame(occdf)) {
        stop("occdf should be of class dataframe")
    }
   
   [ MANUALLY TRUNCATED ]
  
}
NoteReloading the function

The example above is from an R package, where we can use devtools::load_all() to reload all functions.

If you insert browser() in a standalone function, you need to re-execute this function definition before calling it.

In the video below, running the code with the function that now includes browser() doesn’t error. Instead, it stops the execution at the browser() call:

There are two interesting things in this video:

  1. we have access to the function environment, including the user-provided inputs. Note for instance that sub_grid is NULL by default in the function definition, but printing sub_grid in the console gives 250 because the call that is being inspected contains sub_grid = 250.

  2. We can execute the remaining function body statement by statement by pressing “Enter” in the console. Note that this doesn’t necessarily execute all the code: an if() statement whose condition is FALSE will not be executed. browser() follows exactly the path taken by our code.

Pressing “Esc” or executing Q allows us to exit this “browsing” mode.

Using this approach, we can find the exact source of the error:

In our case, the error comes from the line:

occdf <- list(occdf, grid, base_grid, primary, secondary)

Fixing this requires reading all the code prior to this line, but this is beyond the scope of this module.

If you are confident that some lines are irrelevant to the bug, you can move the browser() call past them so that you don’t need to execute them all every time you enter “browsing” mode.

Breakpoints

Breakpoints are a feature directly integrated in the software used to run R (e.g. RStudio or Positron. This is also known as IDE for “Integrated Development Environment”).

They are a way to mimic browser() calls without actually modifying the function. You can add one by clicking on the left of line numbers:

After reloading the package and running the code that is supposed to fail, we end up in almost the same situation as with browser(), except that we haven’t modified the source code at all. We can then follow the same steps to continue our debugging process.

Conclusion

Debugging is an important aspect of programming. This module focused on two essential debugging methods: producing a reproducible example, and using debugging tools such as browser() and breakpoints. Following good debugging practices helps us fix our own code, and it is the essential first step to produce good bug reports. It is also a way to gain experience to recognise potential bugs when reviewing code in the future.



Session info
─ Session info ───────────────────────────────────────────────────────────────
 setting  value
 version  R version 4.6.2 (2026-10-29)
 os       Ubuntu 26.04.1 LTS
 system   x86_64, linux-gnu
 ui       X11
 language (EN)
 collate  C.UTF-8
 ctype    C.UTF-8
 tz       UTC
 date     2026-11-16
 pandoc   3.7.0.2 @ /usr/bin/pandoc
 quarto   1.11.9 @ /usr/local/bin/quarto

─ Packages ───────────────────────────────────────────────────────────────────
 ! package     * version date (UTC) lib source
   ape           5.8-1   2024-12-16 [1] RSPM
   askpass       1.2.1   2024-10-04 [1] RSPM
   base64enc     0.1-6   2026-02-02 [1] RSPM
   bslib         0.12.0  2026-08-04 [1] RSPM
   cachem        1.1.0   2024-05-16 [1] RSPM
   callr         3.8.0   2026-06-05 [1] RSPM
   class         7.3-24  2026-08-03 [2] CRAN (R 4.6.2)
   classInt      0.4-11  2025-01-08 [1] RSPM
   cli           3.6.6   2026-04-09 [1] RSPM
   clipr         0.8.1   2026-05-25 [1] RSPM
 R cpp11         <NA>    <NA>       [?] <NA>
   curl          8.1.0   2026-10-14 [1] RSPM
   DBI           1.3.0   2026-02-25 [1] RSPM
   digest        0.6.39  2025-11-19 [1] RSPM
   dplyr         1.2.1   2026-04-03 [1] RSPM
   e1071         1.7-17  2025-12-18 [1] RSPM
   evaluate      1.0.5   2025-08-27 [1] RSPM
   fastmap       1.2.0   2024-05-15 [1] RSPM
   fontawesome   0.5.3   2024-11-16 [1] RSPM
   fs            2.1.0   2026-04-18 [1] RSPM
   generics      0.1.4   2025-05-09 [1] RSPM
   geojsonsf     2.0.5   2025-11-26 [1] RSPM
 R geometries    <NA>    <NA>       [?] <NA>
   geosphere     1.6-8   2026-04-05 [1] RSPM
   glue          1.8.1   2026-04-17 [1] RSPM
   h3jsr         1.3.1   2023-01-21 [1] RSPM
   highr         0.12    2026-03-06 [1] RSPM
   htmltools     0.5.9   2025-12-04 [1] RSPM
   httr          1.4.9   2026-09-01 [1] RSPM
   jquerylib     0.1.4   2021-04-26 [1] RSPM
 R jsonify       <NA>    <NA>       [?] <NA>
   jsonlite      2.0.0   2025-03-27 [1] RSPM
   KernSmooth    2.23-27 2026-08-12 [2] CRAN (R 4.6.2)
   knitr         1.52    2026-09-06 [1] RSPM
   lattice       0.23-1  2026-08-12 [2] CRAN (R 4.6.2)
   lifecycle     1.0.5   2026-01-08 [1] RSPM
   magrittr      2.0.5   2026-04-04 [1] RSPM
   memoise       2.0.1   2021-11-26 [1] RSPM
   mime          0.13    2025-03-17 [1] RSPM
   nlme          3.1-171 2026-09-01 [2] CRAN (R 4.6.2)
   openssl       2.5.0   2026-11-02 [1] RSPM
   otel          0.3.0   2026-11-07 [1] RSPM
   palaeoverse   1.5.0   2026-06-11 [1] RSPM
   pbapply       1.7-5   2026-09-01 [1] RSPM
   pillar        1.11.1  2025-09-17 [1] RSPM
   pkgconfig     2.0.3   2019-09-22 [1] RSPM
   processx      3.9.0   2026-04-22 [1] RSPM
   proxy         0.4-29  2025-12-29 [1] RSPM
   ps            1.9.3   2026-04-20 [1] RSPM
   purrr         1.2.2   2026-04-10 [1] RSPM
   R6            2.6.1   2025-02-15 [1] RSPM
 R rapidjsonr    <NA>    <NA>       [?] <NA>
   rappdirs      0.3.4   2026-01-17 [1] RSPM
   Rcpp          1.1.2   2026-07-05 [1] RSPM
   reprex        2.1.1   2024-07-06 [1] RSPM
   rlang         1.3.0   2026-07-05 [1] RSPM
   rmarkdown     2.32    2026-09-01 [1] RSPM
   rstudioapi    0.19.0  2026-06-11 [1] RSPM
   s2            1.1.13  2026-09-28 [1] RSPM
   sass          0.4.10  2025-04-11 [1] RSPM
   sf            1.1-3   2026-09-11 [1] RSPM
 R sfheaders     <NA>    <NA>       [?] <NA>
   stringdist    0.9.17  2026-01-16 [1] RSPM
   stringi       1.8.9   2026-08-04 [1] RSPM
   stringr       1.6.0   2025-11-04 [1] RSPM
   sys           3.4.3   2024-10-04 [1] RSPM
   tibble        3.3.1   2026-01-11 [1] RSPM
   tidyr         1.3.2   2025-12-19 [1] RSPM
   tidyselect    1.2.1   2024-03-11 [1] RSPM
   tinytex       0.61    2026-09-17 [1] RSPM
   units         1.0-1   2026-03-11 [1] RSPM
   utf8          1.2.6   2025-06-08 [1] RSPM
   V8            8.2.1   2026-10-26 [1] RSPM
   vctrs         0.7.3   2026-04-11 [1] RSPM
   withr         3.0.3   2026-06-19 [1] RSPM
   wk            0.9.5   2025-12-18 [1] RSPM
   xfun          0.62    2026-10-16 [1] RSPM
   yaml          2.3.12  2025-12-10 [1] RSPM

 [1] /home/runner/work/_temp/Library
 [2] /opt/R/4.6.2/lib/R/library

 R ── Package was removed from disk.

──────────────────────────────────────────────────────────────────────────────