Rlang Conditions

Condition Handling in R Packages

When to Use What

| Task | Use | |------|-----| | Throw formatted error | cli_abort() with message and bullets | | Throw formatted warning | cli_warn() with message and bullets | | Display informative message | cli_inform() with message and bullets | | Show correct function in error | call = caller_env() argument | | Get argument name dynamically | arg = caller_arg(x) in input checkers | | Catch and rethrow with context | try_fetch() with parent = cnd | | Take ownership of low-level error | try_fetch() with parent = NA | | Test error messages | expect_snapshot(error = TRUE, ...) |

CLI Conditions Essentials

Use cli_abort(), cli_warn(), and cli_inform() instead of base R's stop(), warning(), and message() for formatted condition messages.

Basic Usage

# Simple error
cli_abort("Column {.field name} is required")

# Simple warning
cli_warn("Column {.field {col}} has missing values")

# Simple message
cli_inform("Processing {n} file{?s}")

Structured Messages with Bullets

Use named character vectors for multi-part messages:

cli_abort(c(

  "File not found",
  "x" = "Cannot read {.file {path}}",

  "i" = "Check that the file exists"
))

Bullet types:

• "x" - Error/problem (red X)
• "!" - Warning (yellow !)
• "i" - Information (blue i)
• "v" - Success (green checkmark)
• "*" - Bullet point
• ">" - Arrow/pointer

Essential Inline Markup

Format values in condition messages for clarity:

# Arguments
cli_abort("{.arg x} must be numeric")

# Files and paths
cli_abort("Cannot find {.file {path}}")

# Values
cli_abort("Expected {.val TRUE}, got {.val {x}}")

# Classes/types
cli_abort("Expected numeric, got {.cls {class(x)}}")

# Code
cli_abort("Use {.code na.rm = TRUE} to ignore missing values
")

# Function names
cli_abort("See {.fn mypackage::helper} for details")

Pluralization

Use {?} for automatic singular/plural handling:

cli_abort("Found {n} error{?s}")
#> Found 1 error
#> Found 3 errors

cli_abort("Found {n} director{?y/ies}")
#> Found 1 directory
#> Found 5 directories

Error Call Context

By default, abort() and cli_abort() show the function where they are called. When using error helpers, pass call = caller_env() to show the user's function instead.

The Problem

# Error helper without call context
stop_my_class  Error in `stop_my_class()`:
#> ! Something went wrong

The error shows stop_my_class() but users called my_function().

The Solution

stop_my_class  Error in `my_function()`:
#> ! Something went wrong

Now the error correctly shows my_function().

Pattern: Abort Wrapper

stop_my_class  Error in `my_function()`:
#> ! `my_arg` must be a string.

The error shows:

• The correct function (my_function, not check_string)
• The correct argument name (my_arg, not x)

Pattern: Complete Input Checker

check_scalar_numeric  Error in `my_function()`:
#> ! `data` is absent but must be supplied.

Error Chaining

Error chaining adds context when catching and rethrowing errors. Use try_fetch() to catch errors and parent to chain them.

Basic Error Chaining

with_chained_errors  Error in `my_verb()`:
#> ! Problem during step.
#> Caused by error in `1 + "a"`:
#> ! non-numeric argument to binary operator

Why try_fetch() Over tryCatch()

• Preserves full backtrace context for debugging
• Allows options(error = recover) to work
• Catches stack overflow errors (R >= 4.2.0)

Taking Ownership of Errors

Use parent = NA to completely replace a low-level error:

with_user_friendly_errors = 1.0.0 in your package. With testthat >= 3.1.2, this enables the enhanced error display automatically.

### Testing Error Classes

```r
test_that("errors have correct class", {
  expect_error(
    validate_input(NULL),
    class = "validation_error"
  )
})

Resources

rlang Documentation

• Error call documentation
• Error chaining documentation
• Condition customisation

cli Documentation

• cli package
• Semantic CLI article

Style Guide

• Tidyverse error style guide

Reference Files

• [references/error-chaining.md](references/error-chaining.md) - Advanced error chaining patterns
• [references/customisation.md](references/customisation.md) - Condition appearance customization

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jsperger
• Source: jsperger/llm-r-skills
• License: MIT

Install and usage instructions live in the source repository linked above.