Conditions and Error Handling

The help page ?conditions states the model in a few sentences. Conditions are objects that carry information about what happened, such as a message and the call in which it happened; they inherit from the abstract class condition; errors and warnings inherit from the abstract subclasses error and warning; and they are currently S3-style objects, a representation that the help page says may eventually change. In practice a condition is a list with two elements, message and call, and a class attribute that is a vector of class names from the most specific to the most general. That is the same S3 machinery described in S3 Classes and Generics, and it explains everything else on this page: a handler is selected by looking for one of the names in the class vector, a custom condition is a condition with a longer class vector, and extra data is extra list elements.

simpleError(), simpleWarning(), simpleMessage() and simpleCondition() are the constructors for the plain cases. The first three are what stop(), warning() and message() use; simpleCondition() has no severity and is the starting point for conditions that are neither errors, warnings nor messages. conditionMessage() and conditionCall() are generic functions that return the two fields, which matters when a class defines its own method (see below). Printing a condition shows its class, the call after in when there is one, and the message; as.character() gives the text that the default handler would print, Error in <call>: <message> with a trailing newline.

Source: R documentation: conditions

The class vector is the whole type system. simpleError is the most specific class, error says "this is an error" and is what tryCatch(error = ) looks for, and condition is the root that every handler of the form condition = sees. A simple error is not a warning (inherits(e, "warning") is FALSE for the error above). Severity is only a convention of the class vector: warning() signals whatever condition object it is given, so the class decides which handlers see it, not the function that signalled it.

Source: R documentation: conditions

There is a fourth family in the help page that is not signalled by code you write: a user interrupt (the Control-C or Escape key) signals a condition of class interrupt, which inherits directly from condition, before the default interrupt action runs. tryCatch(expr, interrupt = function(i) ...) can intercept it, and suspendInterrupts() and allowInterrupts() mark stretches of code, typically clean-up code, in which interrupts must not (or must) be processed.

The errors and warnings that R raises from its own code are conditions too, built from the same pieces. The call stored in the condition is the call of the function that signalled it, and that is why the messages R prints say Error in log(-1) or Warning in sqrt(-1). Two details of the next script deserve attention. A primitive such as as.integer() has no frame of its own, so a warning raised by it reports the closest enclosing closure call; and a stop() written directly inside tryCatch() reports a call that belongs to the machinery inside tryCatch(), doTryCatch(return(expr), name, parentenv, handler). Neither is a bug; both are why the call of a condition is documentation for people and not something a program should parse.

Source: R documentation: stop

stop("...", call. = FALSE) drops the call, which is the right choice for an error that is addressed to the user of a function and not to its author: the message then starts with Error: and contains nothing but the explanation. The default call. = TRUE is better when the function is deep inside a package and the reader of the message needs to know where it came from. The shelf’s validate_book() uses call. = FALSE for exactly that reason.

stop(...), warning(...) and message(...) take any number of arguments, convert them to character and paste them together with no separator, so stop("invalid year: ", 2200L) and stop(paste0("invalid year: ", 2200L)) are the same call. The three functions differ in what they promise. stop() never returns: once the handlers have had their say and none has taken a non-local exit, the default error action runs. warning() returns its message as a character string, invisibly, when the evaluation goes on. message() also returns when the evaluation goes on (its value is NULL, invisibly), and unlike the other two its text is not a sentence but a line: a final newline is regarded as part of the message, and message() adds one unless appendLF = FALSE. That is why the condition message of message("one line") is "one line\n".

The remaining arguments are small but useful. call. = FALSE (for stop() and warning()) leaves the call out of the condition. domain says where the translation of the message comes from; domain = NA switches translation off, and the help page’s advice is to use it whenever the arguments contain a result from gettextf(), because gettextf() has already translated its text and a second translation attempt would only look up a string that is not in any catalogue. warning(immediate. = TRUE) prints that warning at once even if options(warn) is 0, and warning(noBreaks. = TRUE) asks, with warn = 1, for the message to stay on a single line as far as possible (an argument that is new in R 3.1.0). Long messages are cut: the text of errors and warnings is truncated to getOption("warning.length") bytes, 1000 by default, and a truncated warning ends in [... truncated]. ngettext() is the function to use for messages that depend on a count ("1 loan" and "2 loans"); it is documented with gettext(), and gettextf() with sprintf(). The language of R’s own messages can be switched with Sys.setLanguage() (R 4.2.0), which is the reason code should never test the wording of a message (see Encodings, Locales and Internationalization).

Source: R documentation: message

Source: R documentation: warning

Source: R documentation: gettext

Source: R documentation: sprintf

The second block of the listing shows the default action of message(): with no handler, the text goes to standard error and the script continues. That makes message() the right channel for diagnostics, progress and "I did something you did not ask for" notes, and cat() or print() the right channel for results. A message can be silenced by the caller with suppressMessages() or turned into data by a handler, which cat() cannot.

stop(), warning() and message() are conveniences built on one primitive, signalCondition(cond), which looks for handlers for cond and calls them. The help page for stop() says that an error is first signalled as if by signalCondition(), and ?warning says the same for warnings: the severity-specific part is what happens after the handlers have declined (the default action), not how the handlers are found. Used directly, signalCondition() is the way to announce something that has no default action: if no handler takes the condition, it returns NULL and the code after it runs. A condition of a class such as shelf_note, which is neither an error nor a warning nor a message, is therefore completely optional: nobody has to handle it, and nothing happens when nobody does.

Source: R documentation: conditions

Because the handler for shelf_note returned, the search went on to the next matching handler; there was none, so signalCondition() itself returned NULL and the code after it ran. That is the difference to stop(): a calling handler that returns does not stop an error, it just passes it on.

All three functions also accept a condition object instead of text, and then the object is signalled as it is: its class vector, its message, its call and its extra fields reach the handlers unchanged. This is how classed conditions are raised (the next section builds them with errorCondition()). The condition has to be the only argument. The help pages say that further arguments are ignored, with a warning or a message; the check on R 4.6.1 below did something different: when a second argument is present, stop() builds a character string from all of them (the condition is converted with as.character(), which gives Error: an error built by hand followed by a newline) and signals a plain simpleError with that text. Pass the condition alone.

stopifnot() is a convenience for the most common check: it signals a simpleError whose call is the function that contains the check, with a message that names the failed expression or, for a named argument (R 4.0.0), the text you chose. It is the subject of Defensive Programming and Input Validation, and the last two examples of the listing show it and the domain = NA rule.

Source: R documentation: stopifnot

Code that has to react differently to different failures should not read the message: the text is written for people, it can be translated, and a change of wording breaks every program that parsed it. The robust identity of a condition is its class, and the robust payload is a field. errorCondition(message, ..., class, call) builds an error condition whose class vector is class followed by error and condition; the ... arguments become extra elements of the list, and call defaults to NULL. warningCondition() is the same for warnings, and messageCondition() for messages. The first two arrived in R 3.6.0 (the NEWS describes them as a convenient way to create structured error and warning objects) and messageCondition() in R 4.6.0, completing the set. Message conditions are the least known of the three, and the useful ones: a function can report progress as a message that carries numbers (see the last example of this part), and the caller can log it, show it in a progress bar or silence it by class.

Source: R documentation: conditions

Source: R NEWS: Changes in R 4.6.0

The class vector is built by the constructor, so class = "shelf_invalid_isbn" gives shelf_invalid_isbn, error, condition. It is possible to give several classes (class = c("shelf_invalid_isbn", "shelf_error")) to build a hierarchy of your own: a handler for shelf_error then takes every condition of the family. The convention that keeps the names from clashing with those of other packages is a prefix, the name of your package or project, followed by what happened; the shelf uses shelf_.

The shelf’s validate_book() signals plain errors with stop(..., call. = FALSE): their class is simpleError and only the text tells one failure from another. The wrapper check_book() below re-implements the ISBN check with a classed error (the page does not edit scenario.R; it defines the wrapper next to the example). The condition carries the offending value in the isbn field and the call of the wrapper, and a handler can use either the class or the field. Compare the last two calls: validate_book() signals the same failure as simpleError, so catching only the ISBN case without a class means comparing strings.

Source: R documentation: conditions

Two points about the listing. The handler \(e) e$isbn reads a field, which is the reason to use a condition object: the information survives as data, with its type, and nobody has to parse invalid ISBN-13: 9780306406158 to get it back. And conditionMessage.shelf_invalid_isbn() is an ordinary S3 method on the generic conditionMessage(), so a class can compute its message from its fields; try() and the default error handler use it, and so does tryCatch(error = conditionMessage). Keeping the fields and the message consistent is the author’s job, and a method is the way to avoid storing the same fact twice.

A package with many failure modes benefits from one more level in the class vector: a family class that every condition of the package carries. A caller that wants to treat any failure of the shelf as a shelf problem catches shelf_error; a caller that cares about one failure catches its specific class, listed first. The helper below is the single place where the shelf builds its errors, so the class names, the family and the call are decided once. call = sys.call(-1L) makes the condition name the function that called the helper (lend()), which is where the problem was found, instead of the helper itself.

Source: R documentation: conditions

As the listing shows, the class vector reads from the specific to the general, so the same condition satisfies shelf_invalid_isbn, shelf_error, error and condition handlers. R itself uses the same design: subscriptOutOfBoundsError and packageNotFoundError (see below) are errors with a more specific class in front of error.

Before errorCondition() the same object was built by hand with structure(), a list of message and call plus any extra elements and a class vector ending in error (or warning, message) and condition. The result is the same kind of object, still works, and appears in a lot of older code and tutorials. The only reason to prefer the constructors today is that they say what they mean and make it harder to forget the last two class names.

Source: R documentation: structure

messageCondition() solves a problem that used to need a package: reporting progress from deep inside a function without deciding how it is shown. The function signals a classed message with the numbers as fields; with no handler the text is printed on standard error; a caller that wants a progress bar, a log line or a counter installs a calling handler for the class, reads the fields and muffles the message; and a caller that wants to stop at the first report uses an exiting handler. The muffleMessage restart, explained below, is what stops the default printing. Because the message is also a condition of class message, suppressMessages() silences it with no extra code.

Source: R NEWS: Changes in R 4.6.0

The three severities are a statement about what the caller can do, not about how bad the situation is.

Source: R documentation: conditions

Two habits make conditions easier to use. Write the message for the person who reads it: say what was wrong with which value (invalid ISBN-13: 123), not that "an error occurred", and leave the call out (call. = FALSE) when the reader is a user of the function and the call would only show internals. And do not use print() or cat() to report problems, because neither can be caught, classified or silenced by the caller.

tryCatch(expr, ..., finally) evaluates expr with the handlers given in ... established. Each handler is an argument whose name is a condition class and whose value is a function of one argument, the condition. If nothing is signalled, tryCatch() returns the value of expr. If a condition is signalled, the handlers are searched from the most recently established one, and when several are given in a single call, the first one counts as more recent than the second. When a handler matches, control is transferred to the tryCatch() call that established it: the stack between the signalling code and tryCatch() is unwound (the functions in between are left, their on.exit() code runs, the code after the signalling call is never executed), the handler is called with the condition, and the value of the handler is the value of the tryCatch() call. That is why such a handler is called exiting: it is entered through an exit.

Two consequences are the most frequent reasons for confusion. The first is the order of the handlers. A condition of class simpleError, error, condition is matched against the handlers in the order they are written and the first match wins, even if a later handler is more specific, so condition = before error = makes the error handler dead code. The second is that the handler decides the value. A warning handler that returns "gave up" replaces the value that the code would have produced, and the statements after the warning() call do not run; if the aim is to record the warning and still get the value, use a calling handler (next section).

finally is an expression evaluated after the expression and the handlers, whatever happened. The help page specifies that it is evaluated in the context in which tryCatch() was called, so that the handlers of the current call are no longer active while it runs, and that its value is ignored. It is the place for code that must run on every path, such as closing a connection; on.exit() serves the same purpose for a function body.

Source: R documentation: conditions

A handler is not required to be an anonymous function: identity returns the condition itself, conditionMessage returns its text, and conditionCall its call, as the earlier listings did. A handler that is not a function fails when it is called, not when tryCatch() is set up, with attempt to apply non-function; a handler without a name fails at once with condition handlers must be specified with a condition class, which is what happens when the argument name is forgotten (tryCatch(expr, function(e) ...)).

A handler can decline to deal with a condition by signalling it again, which is how a function adds context or converts a low-level failure into one of its own. stop(e) with the caught object raises the same condition, class and fields included, so an outer handler for shelf_lost still sees it (second example below). If the handler instead calls stop("new text"), a new simpleError is created, and its call is the call of the machinery that invoked the handler, value[[3L]](cond) in the output below. That is the line in Error in value[[3L]](cond) : that people see in logs and wonder about: it is not the call that failed, it is the handler of a tryCatch() that failed. Passing call. = FALSE leaves it out, and building the new condition with errorCondition(), a class and the original condition as a field keeps the information in a form a program can use.

Source: R documentation: stop

R FAQ 7.32 asks how to "capture or ignore errors in a long simulation" and answers with try() and, "preferably", tryCatch(), where the return value can be configured more flexibly: its example returns the coefficients if the lm() call succeeded and a vector of NaN if it failed. The same pattern with the shelf is a loop that builds a book() from each row of books: two rows have an invalid ISBN, row 9 with an empty one and row 13 with a wrong check digit, and book() stops at the first problem of its row. The handler returns the condition itself, so the loop keeps going and the failures are data afterwards: which rows failed and why. Returning NULL or NA instead would keep the loop going too, but would throw the reason away.

Source: R FAQ 7.32: How can I capture or ignore errors in a long simulation?

Source: R documentation: do.call

The list results mixes book objects and simpleError objects, and the vapply() call with inherits(what = "error") tells them apart. A function that has to run over many items and report at the end follows the same shape: catch, keep the condition, summarise. The functional-programming pages show the iteration side (The apply Family and Functionals).

The finally argument is the way to guarantee a clean-up that belongs to a block of code and not to a function. The connection in the example is closed whether readLines() succeeds or fails, and after that the connection object is no longer valid, which is what the last line shows. For clean-up that belongs to a function, on.exit() is the tool (below).

Source: R documentation: textConnection

withCallingHandlers(expr, ...) establishes handlers of a different kind. When a condition is signalled and the matching handler is a calling handler, the handler is called by signalCondition() in the context where the condition was signalled: all the frames of the signalling code are still on the stack, and nothing is unwound. The help page adds that, while the handler runs, only the handlers below it in the handler stack are available, so a condition signalled by the handler itself goes to the outer handlers, not to itself. If the handler returns, the next matching handler is tried, and when the last one has been tried signalCondition() returns NULL and the signalling code goes on, after which the default action for the condition applies: a warning is printed or stored, a message is written to standard error, an error ends the evaluation.

That makes calling handlers the right tool for observing (logging, counting, adding context) and for recovering through a restart, and the wrong tool for replacing a value. They cannot return a value in place of the failed expression; the value of the handler is ignored. A handler that wants to stop the default action has to take a non-local exit, either by calling invokeRestart() or by signalling something else (an error raised inside a calling handler is caught by outer tryCatch() handlers like any other).

Source: R documentation: conditions

The first call shows the order of events in the console: the handler prints its line, the default action then prints the warning (it is Warning in noisy() : because options(warn = 1) is on), and the line after warning() in noisy() does run. The second and third calls muffle: invokeRestart("muffleWarning") and invokeRestart("muffleMessage") jump to restarts that warning() and message() establish around the signalling, and when invoked they make warning() or message() return at once, skipping the default action. The restart is the contract between the signaller and the handler: the function that signals promises a way to carry on, and the handler chooses to use it.

Handlers form a stack, searched from the newest. The next listing prints the call stack inside a calling handler, which makes the idea concrete: outer() and inner() are still active, and below them are the frames of warning() itself and of the restart that it set up (withRestarts(), withOneRestart(), doWithOneRestart()); the last element is the handler. The same listing shows that with two nested withCallingHandlers() calls both handlers run, the inner one first, as long as each one returns.

Source: R documentation: sys.call, sys.calls and sys.function

The frame list is also what traceback() and sys.calls() are made to inspect, and it is the reason a calling handler is the tool for logging the context of an error: it can print sys.calls() before anything is unwound. Debugging with it is covered in Debugging.

Three details come up often. While a calling handler runs, only the handlers below it in the stack are active, so the warning raised inside the inner handler in the first block reaches only the outer handler. When one call lists several handlers, all matching ones are called in the order written (the warning handler and then the condition handler for a warning), as long as each returns; a general condition handler must therefore not assume that the restart it wants exists, which is what tryInvokeRestart() (R 4.0.0) is for. The help page recommends it whenever the condition may come from a foreign context, because a condition of a given class can be signalled by any protocol: a warning object can be signalled with stop() or message(), which do not set up a muffleWarning restart. Calling invokeRestart("muffleWarning") there is an error; calling tryInvokeRestart("muffleWarning") returns silently.

Source: R documentation: conditions

A common request is "give me the result and the warnings that came with it". An exiting handler cannot do that, because it unwinds and replaces the value. A calling handler can: it records the warning in a variable of the enclosing function (with <<-, explained in Scoping, Environments and Closures) and muffles it, and the expression runs to its end. The helper below returns both. Note that as.integer() raises one warning for the whole vector, so a vector with two bad strings produces one entry.

Source: R documentation: warning

Source: R documentation: conditions

A restart is a named place in the code to which a handler can jump, together with a function that runs there. warning() establishes muffleWarning, message() establishes muffleMessage, and the top level has an abort restart that returns to the top level. computeRestarts(cond) lists the restarts that are available (when a condition is given, those that do not apply to it are left out), findRestart(name) returns the newest one with that name, and invokeRestart(r, ...) transfers control to the point where the restart was established and calls its function with the extra arguments; r may be a name, and when no restart has that name the call is an error (no 'restart' 'nope' found). tryInvokeRestart() is the permissive variant that returns invisibly. withRestarts(expr, ...) establishes restarts of your own, in the form name = function (the function is the restart handler), name = "description" (the handler ignores its arguments and returns NULL) or name = list(handler, description, test), where test is a function of the condition that says whether the restart applies to it. restartDescription() and restartFormals() read the description and the arguments.

The value of withRestarts() is the value of the restart function when one was invoked, which is how a handler can supply a value in place of the failed computation: it invokes a restart and passes the value as an argument. Inside an exiting handler, the stack has been unwound already, so the restarts established below the tryCatch() are gone: in the second example only abort remains, and invoking a restart that is not available, as the third call does with muffleWarning, is an error.

Source: R documentation: conditions

The reason restarts exist is that the code that knows how to recover is often not the code that knows whether to recover. A loader knows that a book without a valid ISBN can be skipped or given a placeholder, but not which of the two the application wants; the application knows, but is far away from the loader. With plain errors, the loader would have to take an argument for every policy. With restarts, the loader signals a classed condition inside withRestarts() that offers the ways out, and the caller chooses with a calling handler that invokes one of them. Only the frames between the signalling call and withRestarts() are unwound, so the loop in load_all() carries on with the next book, and the third policy shows the other option: not using a restart at all, so that the condition reaches an exiting handler.

Source: R documentation: conditions

The ISBN of the first failing row is empty (row 9), and the handler for the third policy returned it as the value of tryCatch(): an empty string. The pattern is the one of the Common Lisp restart mechanism, which the help page names as the model for restarts, and it is rare in R code; most packages stop at tryCatch() and the two built-in restarts. Its natural home is a library with a long-running operation (an importer, a downloader) where the right response to a bad item depends on the application.

A warning is a condition, so the handlers come first: a calling handler can log it or muffle it, an exiting handler can stop the evaluation. What happens next depends on options(warn), the integer that ?warning and ?options describe:

Source: R documentation: options

The manual’s chapter on exception handling states the same rule with a slightly different threshold: it says that with fewer than 10 warnings they are printed after the function has finished and with more than 10 only a count, while ?options says "10 or fewer"; a run with exactly 10 warnings on R 4.6.1 printed all ten, which agrees with the help page. The help page also notes that turning warnings into errors may trigger bugs and resource leaks that would not have happened otherwise, so it is a tool for finding the source of a warning rather than a setting for production code (the debugging page uses it that way). Rscript has no special rule: the default is warn = 0, and the scripts of this page ran with the value set to 1 at start-up so that each warning appears at its own position; the next listing sets 0 explicitly to show the default behaviour, and the output shows that the warnings come after the value of the call.

Source: R documentation: warnings

warnings() returns an object of class "warnings", basically a named list: the names are the messages and the elements are the calls. Its length is at most getOption("nwarnings"), 50 by default, which is why the last block (with options(nwarnings = 5)) keeps only five of the twelve. ?warnings suggests raising the limit with something like options(nwarnings = 10000), and ?options adds that the implementation allocates space for the warnings in advance, so a limit above a million or so is a bad idea. summary(warnings()) groups identical warnings and counts them, an addition from R 3.5.0 that the help page calls "somewhat experimental"; the many-warnings case of the listing prints 12 identical warnings:. Before R 4.4.0, warnings() returned NULL when there were no warnings; since then it always inherits from "warnings". The help page also warns that where last.warning is stored is undocumented and subject to change: use warnings(), not the variable.

warn = -1, 1, 2, the immediate. argument, warning.length and warning.expression complete the picture. warning(immediate. = TRUE) turns warn <= 0 into warn = 1 for that call only. warning.length sets the truncation limit of error and warning text in bytes, from 100 to 8170, default 1000; the printed text of a longer warning ends in [... truncated], but the condition object keeps the full text, which the last line of the listing demonstrates (199 characters in the message, a printed line cut at 100). warning.expression is an expression that is called instead of the standard output whenever a warning is generated, whatever the value of warn; the R Language Definition describes it as setting an expression that is evaluated when a warning occurs and says that the normal printing of warnings is suppressed when it is set. showWarnCalls and showErrorCalls control whether the default handlers show a summary of the call stack, which is why script errors have a Calls: line.

Source: R documentation: options

The converted warning in the listing is a simpleError: the original warning is gone, replaced by an error whose message begins with (converted from warning), and a calling handler for warning still sees the warning before the conversion. That is the order to remember when a test suite or a script sets warn = 2 and some code relies on a calling handler for warnings.

Three further options() turn silent behaviour into warnings: warnPartialMatchArgs (partial matching in argument matching), warnPartialMatchAttr (in attr()), and warnPartialMatchDollar (in $). They are explained, with the real warning texts, in Defensive Programming and Input Validation.

If no handler takes an error, the default error action runs. The help page of stop() describes it in detail: the message is printed (if options("show.error.messages") is true), the message is stored where geterrmessage() can find it, a trace of the call stack is stored for traceback(), and then the default error handler of options(error = ) applies. With the default NULL value, an interactive session returns to the top level prompt (or the top-level browser), and a non-interactive one, Rscript for instance, "effectively" calls q("no", status = 1, runLast = FALSE): the script ends, R prints Execution halted, and the exit status is 1, which is what a shell script, a scheduler or a CI job look at (see Scripts and the Command Line).

options(catch.script.errors = TRUE) (R 4.4.0, announced in the NEWS as a documented way to catch errors and then continue in non-interactive use) changes that: the error is printed, evaluation jumps to the top level and continues with the next top-level call. It is meant for something like a report generator, and for this page: it lets one script show many different error messages as R prints them. The format of the message is Error in <call> : <message>; when the call and the message do not fit on a line the message goes on the next line, indented; a Calls: line lists the calls that led to the error when there is more than one (showErrorCalls is on by default in non-interactive use); stop(call. = FALSE) prints Error: <message>; and a warning that was recorded before the error (with warn = 0) is reported after it with In addition: Warning message:.

Source: R documentation: stop

Source: R NEWS: Changes in R 4.4.0

options(error = ) is the legacy interface for global handling of errors (the help page of conditions calls it that while documenting globalCallingHandlers(), below). It takes a function, called with no arguments, or an expression, and runs after the message has been printed. It is how post-mortem debugging is set up: options(error = recover) shows the frames to browse, and options(error = quote(dump.frames(to.file = TRUE))) saves them, as Debugging shows. It runs before the on.exit() expressions of the functions that are being left, as the R Language Definition says; a quick check on R 4.6.1 with a function whose on.exit() prints a line printed the options(error) line first. Two cautions: in a start-up file such as .Rprofile, the function has to be written with its namespace (options(error = utils::recover)), and the option applies only to errors that no handler caught, not to those caught by tryCatch() or try().