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 class 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,
  parent = NULL,
  .subclass = deprecated()
)

warn(
  message = NULL,
  class = NULL,
  ...,
  .frequency = c("always", "regularly", "once"),
  .frequency_id = NULL,
  .subclass = deprecated()
)

inform(
  message = NULL,
  class = NULL,
  ...,
  .file = NULL,
  .frequency = c("always", "regularly", "once"),
  .frequency_id = NULL,
  .subclass = deprecated()
)

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

interrupt()

Arguments

message	The message to display. Character vectors are formatted with `format_error_bullets()`. The first element defines a message header and the rest of the vector defines bullets. Bullets named `i` and `x` define info and error bullets respectively, with special Unicode and colour formatting applied if possible. If a message is 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()`.
parent	A parent condition object created by `abort()`.
.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.
.frequency	How frequently should the warning or message be displayed? By default (`"always"`) it is displayed at each time. If `"regularly"`, it is displayed once every 8 hours. If `"once"`, it is displayed once per session.
.frequency_id	A unique identifier for the warning or message. This is used when `.frequency` is supplied to recognise recurring conditions. This argument must be supplied if `.frequency` is not set to `"always"`.
.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`. If a sink is active, either on output or on messages, messages are printed to `stderr`. This ensures consistency of behaviour in interactive and non-interactive sessions.

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.

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 handle
# technical errors and rethrow them with a more meaningful
# message. Always prefer doing this from `withCallinghandlers()`
# rather than `tryCatch()` because the former preserves the stack
# on error and makes it possible for users to use `recover()`.
file <- "http://foo.bar/baz"
try(withCallinghandlers(
  download(file),
  error = function(err) {
    msg <- sprintf("Can't download `%s`", file)
    abort(msg, parent = err)
}))
# Note how we supplied the parent error to `abort()` as `parent` to
# get a decomposition of error messages across error contexts.

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

}

Signal an error, warning, or message

Arguments

Backtrace

Mufflable conditions

See also

Examples