Skip to content

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.

abort() throws subclassed errors, see "rlang_error".

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.

Usage

abort(
  message = NULL,
  class = NULL,
  ...,
  call,
  trace = NULL,
  parent = NULL,
  use_cli_format = NULL,
  .file = NULL,
  .subclass = deprecated()
)

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

inform(
  message = NULL,
  class = NULL,
  ...,
  use_cli_format = 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. If you supply condition fields, you should usually provide a class argument. You may consider prefixing condition fields with the name of your package or organisation to avoid any conflict in case of subclassing.

call

The execution environment of a currently running function, e.g. call = caller_env(). The function will be mentioned in error messages as the source of the error.

When an error occurs, the corresponding function call (see sys.call()) is retrieved and stored as call field in the error object to provide users with contextual information about the error.

Can also be NULL or a function call to respectively disable the contextual call or hard-code it.

See also local_error_call() for an alternative way of providing this information.

trace

A trace object created by trace_back().

parent

A parent condition object created by abort().

use_cli_format

Whether to format message lazily using cli if available. This results in prettier and more accurate formatting of messages. See also local_use_cli() to set this condition field by default in your namespace.

The downside is that you can no longer format (assemble multiple lines into a single string with lines separated by \\n characters) message ahead of time because that would conflict with cli formatting.

.file

A connection or a string specifying where to print the message. The default depends on the context, see the stdout vs stderr section.

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

Details

  • abort() and warn() temporarily set the warning.length global option to the maximum value (8170), unless that option has been changed from the default value. The default limit (1000 characters) is especially easy to hit when the message contains a lot of ANSI escapes, as created by the crayon or cli packages

Error prefix

As with base::stop(), errors thrown with abort() are prefixed with "Error: ". Calls and source references are included in the prefix, e.g. "Error in my_function() at myfile.R:1:2:". There are a few cosmetic differences:

  • The call is stripped from its arguments to keep it simple. It is then formatted using the cli package if available.

  • A line break between the prefix and the message when the former is too long. When a source location is included, a line break is always inserted.

If your throwing code is highly structured, you may have to explicitly inform abort() about the relevant user-facing call to include in the prefix. Internal helpers are rarely relevant to end users. See the call argument of abort().

Backtrace

abort() always saves a backtrace. You can print a simplified backtrace of the last error by calling last_error() and a full backtrace with summary(last_error()). Learn how to control what is displayed when an error is thrown with rlang_backtrace_on_error.

Muffling and silencing 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().

inform() and warn() messages can also be silenced with the global options rlib_message_verbosity and rlib_warning_verbosity. These options take the values:

  • "default": Verbose unless the .frequency argument is supplied.

  • "verbose": Always verbose.

  • "quiet": Always quiet.

When set to quiet, the message is not displayed and the condition is not signalled.

stdout and stderr

By default, abort() and inform() print to standard output in interactive sessions. This allows rlang to be in control of the appearance of messages in IDEs like RStudio.

There are two situations where messages are streamed to stderr:

  • In non-interactive sessions, messages are streamed to standard error so that R scripts can easily filter them out from normal output by redirecting stderr.

  • If a sink is active (either on output or on messages) messages are always streamd to stderr.

These exceptions ensure consistency of behaviour in interactive and non-interactive sessions, and when sinks are active.

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

}