These functions are equivalent to base functions base::stop(), base::warning() and base::message(), but make it easy to supply condition metadata:

  • Supply .subclass to create a classed condition. Typed conditions can be captured or handled selectively, allowing for finer-grained error handling.

  • Supply metadata with named ... arguments. This data will be stored in the condition object and can be examined by handlers.

interrupt() allows R code to simulate a user interrupt of the kind that is signalled with Ctrl-C. It is currently not possible to create custom interrupt condition objects.

abort(message, .subclass = NULL, ..., trace = NULL, call = NULL,
  parent = NULL, msg, type)

warn(message, .subclass = NULL, ..., call = NULL, msg, type)

inform(message, .subclass = NULL, ..., call = NULL, msg, type)

signal(message, .subclass, ...)

interrupt()

Arguments

message

The message to display.

.subclass

Subclass of the condition. This allows your users to selectively handle the conditions signalled by your functions.

...

Additional data to be stored in the condition object.

trace

A trace object created by trace_back().

call

Deprecated as of rlang 0.3.0. Storing the full backtrace is now preferred to storing a simple call.

parent

A parent condition object created by abort().

msg, type

These arguments were renamed to message and .type and are deprecated as of rlang 0.3.0.

Backtrace

Unlike stop() and warning(), these functions don't include call information by default. This saves you from typing call. = FALSE and produces cleaner error messages.

A backtrace is always saved into error objects. You can print a simplified backtrace of the last error by calling last_error() and a full backtrace with summary(last_error()).

You can also display a backtrace with the error message by setting the experimental option rlang__backtrace_on_error. It supports the following values:

  • "reminder": Invite users to call rlang::last_error() to see a backtrace.

  • "branch": Display a simplified backtrace.

  • "collapse": Display a collapsed backtrace tree.

  • "full": Display a full backtrace tree.

Mufflable conditions

Signalling a condition with inform() or warn() causes a message to be displayed in the console. These messages can be muffled with base::suppressMessages() or base::suppressWarnings().

On recent R versions (>= R 3.5.0), interrupts are typically signalled with a "resume" restart. This is however not guaranteed.

Lifecycle

These functions were changed in rlang 0.3.0 to take condition metadata with .... Consequently:

  • All arguments were renamed to be prefixed with a dot, except for type which was renamed to .subclass.

  • .call (previously call) can no longer be passed positionally.

See also

with_abort() to convert all errors to rlang errors.

Examples

# These examples are guarded to avoid throwing errors if (FALSE) { # Signal an error with a message just like stop(): abort("Something bad happened") # Give a class to the error: abort("Something bad happened", "somepkg_bad_error") # This will allow your users to handle the error selectively tryCatch( somepkg_function(), somepkg_bad_error = function(err) { warn(err$message) # Demote the error to a warning NA # Return an alternative value } ) # You can also specify metadata that will be stored in the condition: abort("Something bad happened", "somepkg_bad_error", data = 1:10) # This data can then be consulted by user handlers: tryCatch( somepkg_function(), somepkg_bad_error = function(err) { # Compute an alternative return value with the data: recover_error(err$data) } ) # If you call low-level APIs it is good practice to catch technical # errors and rethrow them with a more meaningful message. Pass on # the caught error as `parent` to get a nice decomposition of # errors and backtraces: file <- "http://foo.bar/baz" tryCatch( download(file), error = function(err) { msg <- sprintf("Can't download `%s`", file) abort(msg, parent = err) }) # Unhandled errors are saved automatically by `abort()` and can be # retrieved with `last_error()`. The error prints with a simplified # backtrace: abort("Saved error?") last_error() # Use `summary()` to print the full backtrace and the condition fields: summary(last_error()) }