Debugging

This is the same failing report in an interactive session. Because the session keeps source references, an entry for a call that sits inside a function typed at the prompt ends in at #n, the line of that function’s definition on which the call is written.

Source: R documentation: traceback

Reading the numbers from the bottom, member_report() called count_overdue() from line 3 of its definition, which called vapply() from line 2 of its own definition, which called the anonymous function, shown as FUN(X[[i]], ...), which called is_overdue() from line 3 of the definition of count_overdue() (the anonymous function is part of that definition, so its lines are counted there); and the error was detected in is_overdue(). The anonymous function \(i) ... is shown as function(i) {...}: the backslash form is only a different way of typing the same call. The last command, .traceback()[[1]], shows that the stack is data: .traceback() returns the stack as a list or pairlist of calls, deepest first, with each call as a character vector of deparsed lines, and traceback() formats and prints that list. .traceback() was added in R 3.3.0, and since R 4.0.0 the stack that R records when the error is signalled (.Traceback) holds the calls themselves and deparses them only when traceback() or .traceback() is called; the help page warns that where .Traceback is stored is undocumented, so use the functions, not the variable.

An Rscript run ends at the first uncaught error, so there is no prompt at which to type traceback(). The error option fixes that: it holds a function, or an expression, that R runs when an error reaches the top level, after printing the message and before it halts. The next script prints the traceback from such a handler and then leaves with q(status = 0). The argument 3 of traceback() means "skip three entries at the top of the stack": the entries for traceback(), .traceback() and the handler that called them, which the help page recommends for exactly this use.

Source: R documentation: traceback

The first three lines are R’s own message and Calls: summary; everything from 5: down is traceback(3). With traceback(2) the handler itself would show up as the top entry, and for an error raised by stop() the stop() call is an entry too, as the next script shows with the smallest possible chain. The handler in this script also reads the stack through .traceback(3). Called directly from the handler, .traceback(3) skips three entries too, but they are .traceback() itself, the handler and the stop() call, so what it returns is the three frames of f(), g() and h().

Source: R documentation: traceback and .traceback

The handler appears in the traceback as an anonymous function call, (function () {...})(), because R evaluates the error option as a call to the function. The stop("boom in h") entry is frame 4, above h(x), since stop() is itself a function call and the error is signalled from inside it. The class: pairlist line is a detail worth knowing when you process the result: the help page says .traceback() returns a list or a pairlist, and for the stack of an error it is a pairlist, so wrap it in as.list() before using lengths() or vapply() on it (the script below does).

The error option takes any of three forms. A function is called with no arguments (options(error = function() ...), or the name of one such as recover). An expression is evaluated: options(error = quote(...)) or an expression() vector, which is the form that fits the one-liners in the manuals. And NULL, the default, restores the standard behaviour: return to the prompt in an interactive session, halt in a non-interactive one. In start-up files the functions of the utils package have to be written with the namespace, as options(error = utils::recover), because the package is not yet attached when the file runs (the options help page says so). A traceback() that is very long can be shortened: max.lines limits the number of lines printed per call, and the options traceback.max.lines and deparse.max.lines set the limit for the whole session. A long call is what do.call() produces when the function is given the objects themselves: the call that R records holds the values, not the names, so a data frame argument is pasted into it. The next script shows how long such an entry gets, and what max.lines = 2 does to it.

Source: R documentation: traceback (max.lines)

The failing function was reached through do.call("first_overdue", list(loans)), so its entry in the stack, number 2, contains the whole data frame as an argument: lengths() counts 50 lines for it against 1 for the others, and max.lines = 2L keeps the first two lines of it and marks the cut with .... With a function object instead of its name, do.call(first_overdue, list(loans)), the entry would begin with the deparsed function as well. Either is a reason to pass names of objects, not objects, through do.call() when the call may appear in a traceback; see Evaluation and Non-Standard Evaluation for do.call() itself.

It reports the stack of the last uncaught error, and only that. An error caught by try() or tryCatch() generates no traceback, and neither does a warning; the help page says that what traceback() prints is the call sequence for the last uncaught error and not necessarily for the last error. The stack ends where the error was signalled, so it cannot tell what the values were. Writing R Extensions gives three more reasons it may not point at the cause. If the innermost call is .C, .Fortran, .Call, .External or .Internal, the error came from compiled code, and as such code can evaluate R expressions the compiled call need not be the innermost one. When S4 method dispatch is involved the traceback can stop at a call such as initialize(value, ...) while the error message names a function that is not in the stack. And for infinite recursion the message evaluation nested too deeply: infinite recursion / options(expressions=)? can be hard to read at the default limit of 5000 nested expressions, so the manual suggests lowering it with options(expressions = 500) and running the example again (the script below does this). In all three cases the tools of the next sections, which stop the program while it is still running, give more.

A calling handler runs on top of the stack of the condition it handles, before anything is unwound, so it can read the live stack with sys.calls() (R documentation: sys.parent and its relatives). That is the one way to get a stack for a condition that a tryCatch() further out would catch, and the way to log the stack of an error without stopping the program. tryCatch(), by contrast, unwinds first, so its handler sees only the frames outside it. The script below logs the stack of the failing report and then lets the error continue to try().

Source: R documentation: conditions (withCallingHandlers)

Frames 1 to 6 are the machinery of try() and tryCatch() that this particular script wraps around the call, 7 to 10 are the code under test, in the same order as in the traceback, and 11 and 12 are R’s own signalling code, which a handler always sits on top of: .handleSimpleError() and the call of the handler h(). The handler then returned, so the error continued to try(), which returned an object of class try-error because of silent = TRUE. The same calls list could be written to a log file instead of printed, or passed to traceback(), which accepts a list of calls as well as a number.

Stopping on every iteration of a loop is useless when the interesting one is the 512th. browser(expr = <condition>) evaluates the condition and enters the prompt only when it is true. The help page says that it is an illusion of conditional debugging, because execution is always paused at the call and the condition only decides whether control passes to the evaluator, and that an if statement around a bare browser() is usually more efficient; the argument is simply shorter to write in a place where an if is awkward. The text argument labels the stop, so that browserText() can tell several breakpoints apart.

The function in the transcript counts the loans in a data frame that were returned before they were lent. The browser stops only for the loan that is wrong, the loop variable i and the data say which one, and the edit to days at the prompt keeps the loan out of the count.

Source: R documentation: browser (expr, text and browserText)

The first loan whose period is negative is the twelfth, L012; the label passed as text comes back from browserText(); the variable days was set to 0 at the prompt, so bad is still 0 when the loop continues, and the function returns 0 where it would have returned 1.

The number in Browse[1]> is the browser level. A browser entered from the prompt of another browser is one level deeper: typing a call to a function that itself contains browser() gives Browse[2]>, where shows the nested call on top of the stack, and c returns to level 1. debug() replaces its browser at every step rather than nesting a new one, which is why its prompt stays at Browse[1]>.

Source: R documentation: browser (the browser prompt and its levels)

After the first c returns to level 1, the second c lets late_days() carry on to its call of days_out(), whose own browser() stops again at level 1; Q quits everything. The help page adds a point about handlers: the browser prompt is implemented with the restart and condition-handling mechanism, so it prevents error handlers set up before the breakpoint from being invoked while you are at the prompt, and an error you type goes back to the prompt. Handlers for other classes, such as "warning", are still called and can transfer control out of the debugger.

The prompt reads its commands from the console. When a script is run with Rscript there is no person at the console, and what the browser reads is the rest of the script file: the lines that follow the call become the browser’s commands. The script below calls a function with a browser() in it and then has three more lines of its own; the output after it, from Rscript on R 4.6.1, shows that those lines were run at the browser prompt.

Source: R documentation: browser

Source: An Introduction to R: Scripting with R

The output is a record of what was observed, not a documented behaviour: Called from: f(1) is the browser announcing itself; after the call, [1] 20 are the output of the lines cat("after the call\n") and y * 10, run in the frame of f(), and y <- 2 ran there too, as a local variable of f(); at the end of the file the browser got no more input, stepped on (debug: x + 1) and f(1) returned 2. The lesson is to remove browser() calls before running code in a batch job. debug() and trace() with a browser tracer behave the same way. Since R 4.3.0 the environment variable _R_CHECK_BROWSER_NONINTERACTIVE_ makes non-interactive debugger invocations trappable, and R CMD check --as-cran enables it to detect leftover browser() statements in a package (R NEWS: Changes in R 4.3.0). Section Scripts and the Command Line covers running R non-interactively.

R compiles functions to byte code after a couple of calls (the just-in-time compiler, enabled by default since R 3.4.0, which NEWS says will not compile code that contains explicit calls to browser(), to support single stepping from that call). The browser help page adds that for byte-compiled functions interrupted by browser(), n and s are equivalent to c, and the debug() help page that when debugging is enabled on a byte-compiled function the interpreted version is used until debugging is disabled.

debugonce(fun) clears itself on the first call. It is the version to use when the function is called many times and only one call matters, or to avoid forgetting undebug(). Its flag is not the one isdebugged() reports, and undebug() does not clear it:

Source: R documentation: debug (debugonce and isdebugged)

After debugonce(late_days), isdebugged(late_days) is FALSE, and undebug(late_days) warns that the argument is not being debugged and does nothing to the pending one-shot flag. The next call stops, c runs the function to its end and the flag is gone: the second call is not debugged. If a pending debugonce() is no longer wanted, the only way to clear it is to make the call it was waiting for. The text and condition arguments of debug() and debugonce() are the same as those of browser().

debug() accepts a function or the name of one in a character string, any interpreted R function. For a function in a package the usual forms are debugonce(pkg::fun) for an exported one and debug(pkg:::fun) for one that is not exported or is a registered S3 method, as in the manual’s debug(stats:::predict.Arima). The next session debugs stats::sd(), which is a plain R function:

Source: R documentation: debug

A function without a source reference prints debug: rather than debug at #n:; the browser shows its arguments (ls() lists na.rm and x) and the statement that is about to run, here the whole body of sd(), deparsed over two lines. Source references of installed packages are absent unless the package was installed with options(keep.source.pkgs = TRUE) (or the environment variable R_KEEP_PKG_SOURCE=yes), which is why the RStudio guide advises building a package under development with source information kept.

For a function defined inside another function, the R manuals give the procedure: set debug() on the outer function, step through it until the inner function has been defined, call debug() on the inner function’s name, and use c to get out of step-through mode in the outer one. If you want to debug a function not starting at the very beginning, the help page points to trace(..., at = *) and to setBreakpoint(), described next.

Two more functions complete the family. debuggingState() is the global switch: debuggingState(FALSE) turns every debug flag off without removing them, debuggingState(TRUE) turns them on again, and debuggingState() reports the state; explicit browser() calls keep working either way. The next script shows the flags and the switch without entering the browser, which an unattended script cannot use sensibly:

Source: R documentation: debug (isdebugged and debuggingState)

The values printed by debuggingState(FALSE) and debuggingState(TRUE) are the previous states, as for options().

With browser as the tracer, trace() is a breakpoint at a chosen statement: the manual’s own example is trace(glm.fit, browser, at = 22) after printing as.list(body(glm.fit)) to find the number. The next transcript sets one before the statement that computes the result in late_days(), steps once, continues, removes the trace and checks that the function is back to normal.

Source: Writing R Extensions: Debugging R code

trace() prints the name of the function and the call that was made, with the step: Tracing late_days(...) step 3. The prompt says Called from: eval(expr, p), and where shows why: the browser was started from inside the code that trace() inserted, which is evaluated by .doTrace() and a couple of eval() calls. Those frames are not part of your program; the environment the prompt works in is that of late_days() (days printed -3), and the first statement shown after n is the one the trace was set before. The manual’s transcript of this example shows Called from: eval(expr, envir, enclos), a different spelling of the same label. The examples in the help page of trace() pass browser(skipCalls = 4) as the tracer so that the reported location skips such frames. untrace(late_days) restores the function.

An exit tracer works at the other end of the call: it can look at the value being returned. The session below traces days_out() with an expression tracer that opens the browser at the start and prints the return value at the exit.

Source: R documentation: trace (exit and returnValue)

The browser stops on entry, where return_date can be read, and c lets the function run to its exit, where print(returnValue()) prints [1] -3 before the caller prints its own result, [1] 0.

findLineNum() finds the function and the step that contain a given line of a source file, and setBreakpoint() is a wrapper that calls trace() for it, with browser as the default tracer. Both read the source references that R stores when code is parsed with keep.source = TRUE, so the code must have been read with source(file, keep.source = TRUE) (the Rscript default is FALSE) or typed at an interactive prompt. The file name is matched by its base name unless nameonly = FALSE, and "file.R#nn" gives the line (R documentation: findLineNum and setBreakpoint). By default they search the global environment; for code inside a package namespace or for S4 methods the envir and lastenv arguments widen the search. The RStudio user guide describes its editor breakpoints in similar terms (see below).

Source: R documentation: findLineNum and setBreakpoint

The script writes the file itself, in the temporary directory, so that it is self-contained, and removes it at the end. Line 3 of the file holds the second statement of days_out(), which is step 3 of its body (the first statement is step 2, as before). The breakpoint at line 4 ran the tracer, here a cat() expression instead of the default browser so that the script can run unattended, before the line that returns days; the call returned 29 days, and after clear = TRUE the same call printed nothing extra.

The help page lists the limits. Tracing does not nest: a call to trace() replaces any earlier tracing of the same function, except for edited versions, and untrace() always restores the untraced function. The exit argument will not work if the function itself uses on.exit() without add = TRUE, because the existing call overrides the one trace() adds. Tracing a primitive works only by a special mechanism, replaces the primitive by a function of ..., gives little information, and issues a warning. The traced object is saved back where the function came from, so tracing of a function in the global environment survives in a saved workspace image and goes on in the next session, where untrace() removes it, while functions in packages are not saved with the image, so tracing of them ends with the session. The browser reached through trace() is the ordinary one. Fixes in recent releases show where the edges are: trace() of coerce works correctly since R 4.5.0, isS3stdGeneric() (used by debugcall()) has recognised an S3 generic that is being traced since R 4.0.3, and R-devel, the development version that will become R 4.7.0, makes trace() work for functions whose class attribute has more than one string, such as S7 generics and methods, and fixes a bad call that trace() could insert when tracing rematched S4 methods (R-devel NEWS; upcoming, not run here).

recover() is a function meant to be the error option. When an error reaches the top level, R prints the message and recover() prints the active calls as a numbered menu. Choose a number, and the browser opens in the frame of that call: the variables there are the ones the call had when the error struck. c leaves the browser and returns to the menu, another number browses another frame, and 0 exits. Nothing is re-run and nothing is copied, which the help page names as its advantage over dump.frames() when the computation involves large data. The session below uses a deliberately wrong call, with dates given as strings, so that end - loan_date fails inside days_out().

Source: R documentation: recover

Frame 2 is the call that failed: its ls() shows end, loan_date and return_date, and end holds the string "2026-06-01", which is why the subtraction fails. Frame 1 is the caller: ls() there shows only the arguments, because late_days() was still waiting for days_out() to return, so days does not exist yet. The label 2: #2: days_out(...) carries the source reference of the call. Called from: top level is cosmetic: the browser is evaluating in the chosen frame, as the variables show, though the label does not name it. After the session options(error = NULL) restores the standard behaviour, and the traceback() that follows shows that the stack of the error is still available.

In a non-interactive session recover() has no one to ask, so it behaves like dump.frames(), as the help page says. The script below shows that in Rscript: the message says so, the frames are dumped to last.dump and the script goes on with the next top-level call.

Source: R documentation: recover

The names of last.dump that were not printed are the frames of recover() itself and of the machinery around it; the first three are the stack of the error.

dump.frames() saves the stack: the calls and the environments of the active frames, plus the last error message. Used as the error option, options(error = dump.frames), it stores them in an object named last.dump in the workspace, and debugger() browses it. The signature is dump.frames(dumpto = "last.dump", to.file = FALSE, include.GlobalEnv = FALSE); to.file = TRUE writes the dump to the file <dumpto>.rda instead of the workspace, and include.GlobalEnv = TRUE (added in R 3.4.0) also stores a copy of the global environment, which the help page calls particularly useful in a batch job. The result is a list of environments named by the calls, with class dump.frames. Writing R Extensions warns that such objects can be large, so remove last.dump when it is no longer needed. The first script shows the dump in an Rscript run, where installing dump.frames as the error option keeps execution going, as the help page notes.

Source: R documentation: dump.frames and debugger

The error.message attribute holds what geterrmessage() held when the error happened, including the Calls: line that a non-interactive session adds; there are four frames, because stop() is a frame too; and each element is an ordinary environment, so ls() and get() work on it. debugger() is the interactive way to look at them. In a live session:

Source: R documentation: debugger

debugger() with no argument uses last.dump; it prints the message and the calls in outer-first order, the opposite of traceback(), then asks for an environment number. Choosing a frame opens the browser, c returns to the list, 0 leaves. There is a difference from recover() that the help page spells out: the selected environment is copied and the browser is called from the copy, so not everything in the original frame is available, such as promises that have not been evaluated and the contents of .... The page’s note adds that sys.parent() and environment() applied to closures do not work correctly inside debugger(), and that an error raised while computing a default argument is reported as "recursive default argument reference" when that environment is examined. For anything that depends on lazy arguments, use recover() or browser().

A batch run has nobody to ask, but the dump can be saved for later: options(error = quote({dump.frames(to.file = TRUE); q()})) is the manual’s setting (Writing R Extensions: Debugging R code), and the help page’s setting for non-interactive sessions ends in q(status = 1), so that the exit status of the job reports the failure. The expression is wrapped in quote() so that it is stored in the option instead of being evaluated at once, and the function is written utils::dump.frames so that it also works in a start-up file, where utils may not be attached yet. This script is meant to fail: it writes last.dump.rda into the working directory, prints the error and exits with status 1. That is not a defect of the example; the exit status is the point.

Source: R documentation: dump.frames and debugger (a possible setting for non-interactive sessions)

Later, in another session on the same or on another machine, the dump is loaded and examined. The loading script prints what it contains and then deletes the file, so it leaves nothing behind:

Source: R documentation: load

and the interactive look at the same file, with debugger(last.dump) on the object that load() created, is:

Source: R documentation: debugger

Since last.dump holds environments, it can be debugged in a later session even though the original process is gone, which is what makes post-mortem debugging possible for batch use, according to the manual; the alternative it mentions is saving the workspace at the end of the run with the --save command-line flag.

Setting browser itself as the error handler works, but not the way recover does. The handler is called from the top level, so the browser opens in the global environment and not in the frame of the failing call: the label says Called from: days_out(...), and where shows the stack, but the variables in scope are the global ones.

Source: R documentation: options (error)

The RStudio user guide writes the always-debug setting as options(error = browser()). In plain R, with the parentheses, browser() is evaluated when options() is called, not when an error happens, so the browser opens at once and the option is left unset:

Source: R documentation: options (error)

The transcript shows that getOption("error") is NULL after the call and the later error just returns to the prompt. The working forms are a function name, options(error = recover), or an expression such as options(error = quote(browser())). How RStudio treats the guide’s form was not tested here; the guide itself says the setting overrides RStudio’s error-handler settings and advises changing it back (with options(error = NULL)) when troubleshooting is over, since trapping every error becomes annoying.

R 4.4.0 added a documented option for the other common batch need, to carry on after an error: with options(catch.script.errors = TRUE), an error in a non-interactive script is reported and evaluation continues with the next top-level expression, instead of ending the run. The options help page says to use it with care; later steps may depend on the one that failed. Its help text also says that traceback() provides information about the error. The script shows the continuation, the traceback, and showErrorCalls = FALSE, which removes the Calls: line.

Source: R documentation: options (catch.script.errors, showErrorCalls)

The traceback has three entries because stop() is a call too, and the second error is reported without the Calls: line. The option is a switch for the whole script. For a long simulation in which a few iterations may fail, R FAQ 7.32 recommends try(), which returns an object of class "try-error", or preferably tryCatch(), where the value to use for a failed step can be chosen (R FAQ 7.32); that keeps the result of the successful steps and says exactly which step is replaced.

The error evaluation nested too deeply: infinite recursion / options(expressions=)? is raised when the number of nested expressions reaches the limit set by options(expressions =), 5000 by default, and the manual’s advice is to lower it, for example to 500, and run again so that the traceback is short. R 4.2.0 made stack-overflow errors conditions that inherit from stackOverflowError. The help page lists the specific classes: CStackOverflowError for the C stack, protectStackOverflowError for the pointer protection stack, nodeStackOverflowError for the node stack of the byte-code engine and expressionStackOverflowError for the limit of nested expressions, so a handler can tell them apart (R documentation: StackOverflows). The help page also says that such errors can be caught by exiting handlers established with tryCatch(), but that calling handlers may fail because there may not be enough stack to run them, which is why the script catches the error with tryCatch().

Source: R NEWS: Changes in R 4.2.0

The valid values of expressions are 25 to 500000 according to the options help page, which also warns that increasing it may cause a segfault from overflow of the C stack. The script restores the default after catching the error, and the error is of class expressionStackOverflowError first, then stackOverflowError, error and condition.

For an S3 generic, debug(fun) flags the generic, which does little except dispatch; the method that runs is the thing to flag. When the method is visible, debug(format.book) works. For a method that is not exported, use the triple colon (debug(stats:::predict.Arima) in the manual) or getS3method(). utils::debugcall() does the lookup for you: given a call, it sets the flag on the non-generic function, S3 method or S4 method that evaluating the call would run, based on the classes of the arguments, and undebugcall() clears it. It was added in R 3.4.0 together with the signature argument of debug(), and R 4.4.1 made debugcall(S3Generic()) work when a corresponding S4 generic version is in the methods cache. The help page notes that it uses non-standard evaluation to get the call, so a variable holding a call does not work, and that for non-standard S3 generics the generic itself is debugged. It does not run the call; the idiom eval(debugcall(summary(f))) evaluates it afterwards.

Source: R documentation: debugcall

The session that follows uses the flag for real. The browser is in the method format.book(), which the scenario defines in scenario.R, and its source references name the file and line, scenario.R#80, because source() kept them:

Source: R documentation: debugcall

R FAQ 8.5, "How can I debug S4 methods?", answers in one sentence: use trace() with the argument signature= to add calls to the browser, or any other code, to the method that will be dispatched for the corresponding signature (R FAQ 8.5). Writing R Extensions says that debug() "cannot be used for S4 methods"; that text predates R 3.4.0, which added the signature argument to debug(), debugonce(), undebug() and isdebugged(). Since then debug(fun, signature = ) works, implemented with the trace machinery; later releases extended it: R 3.5.0 supports methods on any object of class genericFunction, including group generics, and R 4.5.0 accepts a string that names an S4 generic. The script defines a tiny S4 class (the methods package is attached by Rscript), traces a method and the show() method, and uses isdebugged() with a signature.

Source: R documentation: debug (signature)

The method that was traced is the one for Book; the tracer printed before the result of age_in(bk), and not after untrace(). Autoprinting a Book called the show() method, so tracing it with signature = "Book" printed the tracer line once. isdebugged("age_in", signature = "Book") is FALSE before debug(age_in, signature = "Book") and TRUE after, and isdebugged("age_in") for the generic stays FALSE, since the generic was not flagged. The comment in the script points at a quirk of R 4.6.1: when the generic lives in the global environment, undebug("age_in", signature = "Book"), with the generic’s name as a string, fails with no function ‘age_in’ found, because the lookup runs in the methods namespace; passing the generic function itself, undebug(age_in, signature = "Book"), or using untrace("age_in", signature = "Book"), works. The interactive version of the same session:

Source: R FAQ 8.5: How can I debug S4 methods?

debug() by signature inserts a browser tracer at step 2 of the method, so it announces Tracing age_in(bk) step 2 and the label is again Called from: eval(expr, p). After undebug() the same call runs without stopping. If a method adds arguments that the generic does not have, R rewrites it so that the body is a local function called .local, and what has to be traced is that function. debug() handles it for you (the manual’s phrase is "rematched"), and isRematched() tells which methods are of this kind:

Source: R documentation: trace (tracing rematched S4 methods)

body(getMethod("label_of", "Book")) shows the wrapper: .local is defined in the method and called with x and the dots. Tracing with signature found the inner function by itself; the message Tracing function ".local" in package ".GlobalEnv" appears at the first dispatch after tracing, before the tracer’s own output, and upper was visible to the tracer because .local is where upper is an argument. R-devel’s NEWS mentions a fix for an improper call that trace() could insert for rematched methods; see the section on trace(). S4 classes and methods themselves are in S4 Classes and Methods.

Not every bug needs a debugger. Output that is cheap to leave in is worth having: message() writes to the error stream, so it does not mix with a function’s printed result and can be silenced with suppressMessages(); str() and dput() show what an object really is, which is often the bug, such as a Date that is a number with a class; and on.exit() reports how a function was left, including by an error. The following script uses all of them on the shelf’s loan with the impossible dates.

Source: R documentation: message

dput(loans$return_date[12]) shows structure(20198, class = "Date"), and dput(unclass(...)) the bare number of days since 1970-01-01. The on.exit() line is printed in both runs, also in the one that ends in an error; Functions describes on.exit() and its add argument. A stopifnot() placed where a value must satisfy a condition turns a silent wrong result into an error at the earliest line that can detect it, and the stack then points there; that technique is the subject of Defensive Programming and Input Validation.

The user guide organises debugging around the ways to enter debug mode (RStudio user guide: Debugging).

When code is stopped, the console prompt becomes Browse[1]>, the Environment pane shows the environment of the running function instead of the global one, with arguments that have not been evaluated shown in gray as promises, and a drop-down list shows the chain of enclosing environments. The traceback shares the space of the Environment pane; the guide says it shows the call stack and is called the traceback for symmetry with traceback(), that clicking a frame shows its variables and code without changing the active environment of the console (use recover() for that), and that internal functions are hidden unless View Internals is ticked. The code window highlights the line about to run. The console toolbar sends the same commands as the table in the browser() section:

Source: RStudio user guide: Debugging (Debugging commands)

The guide has a section on special circumstances, and they follow from how the mechanisms work. Breakpoints that are outside any function cannot be injected into a function object, so RStudio provides debugSource(), a source() that stops at those breakpoints; it is not recursive, so a file that is itself sourced by the debugged file is not stopped in. Package code needs an up-to-date build, and the package should be compiled with source information (--with-keep.source) for the breakpoints to be placed. In Shiny applications breakpoints work only inside the shinyServer function, not in ui.R or global.R, and a lot of Shiny infrastructure shows in the call stack before control reaches your code. In R Markdown breakpoints do not currently work in chunks, so use browser(); the Knit button renders in a separate R process, where the debugger cannot reach, so call rmarkdown::render() from the console to render in the primary process; the debugger’s output is not shown while knitr is capturing output, so call sink() at the Browse[1]> prompt, or set options(error = function() { sink(); recover() }) in the setup chunk (which ends with a harmless "no sink to remove" warning). For Quarto documents with the knitr engine, rmarkdown::render() is likewise recommended, and quarto::quarto_render() is documented as currently not compatible with these strategies. These two use the knitr and rmarkdown packages; they were not run here.

Positron’s R support is provided by Ark, an R kernel. Its README describes three roles: a Jupyter kernel, a Language Server Protocol server for completions and diagnostics, and a Debug Adapter Protocol server for "sophisticated step-debugging of R functions" that manages source references, creating them on the spot if needed, and integrates with the kernel to step through R code and inspect local variables (Ark README). The same README, as read on 2026-10-20, says that support for breakpoints is currently missing and that debug(), debugonce() or browser() can be used to drop into the debugger. That is a statement with a date: the navigation of the Positron documentation pages that were read lists a "Debugging R code" guide, which was not among the pages checked, and the release notes should be consulted for the version in use before relying on either. The Positron features page presents the Variables pane as the place to examine variables, objects and environments while debugging. The R functions on this page are ordinary R and are available in the Positron console as in any other front end; debug(), debugonce() and browser() are the ones the README names. See IDEs and the R Console for the other front ends, including the community debugger extension for Visual Studio Code, and for the console-level view of the same tools.

R FAQ 6.3, "Debugging R from within Emacs", is about running the R binary under gdb, the GNU debugger for compiled code, from Emacs, either with the GUD library or by attaching to an inferior R process started from ESS (R FAQ 6.3).