Signal an error, warning, or message

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 = NULL,
  class = NULL,
  ...,
  trace = NULL,
  call,
  parent = NULL,
  msg,
  type,
  .subclass
)

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

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

signal(message, class, ..., .subclass)

interrupt()

Arguments

message	The message to display. If not supplied, it is expected that the message is generated lazily through conditionMessage(). In that case, class must be supplied. Only inform() allows empty messages as it is occasionally useful to build user output incrementally.
class	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	Defunct as of rlang 0.4.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 .subclass and are defunct as of rlang 0.4.0.
.subclass	This argument was renamed to class in rlang 0.4.2. It will be deprecated in the next major version. This is for consistency with our conventions for class constructors documented in https://adv-r.hadley.nz/s3.html#s3-subclassing.
file	Where the message is printed. This should be a connection or character string which will be passed to cat(). By default, inform() prints to standard output in interactive sessions and standard error otherwise. This way IDEs can treat messages distinctly from warnings and errors, and R scripts can still filter out the messages easily by redirecting stderr.

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 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.

• "none": Display nothing.

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(conditionMessage(err)) # 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())

}