Fail Early

If something is going to fail, it should fail as early as possible, as loud as possible, with as much context as possible. This skill codifies fail-early pattern: check inputs at system edges, use guard clauses to reject bad state before it spreads, and write error msgs that answer what failed, where, why, and how to fix it.

When Use

• Writing or reviewing functions that take external input (user data, API responses, file content)
• Adding input check to package functions before CRAN submit
• Refactor code that silently makes wrong results instead of erroring
• Reviewing PRs for error-handle quality
• Harden internal APIs vs bad args

Inputs

• Required: Function or module to apply pattern to
• Required: Spot of trust edges (where external data enters)
• Optional: Existing error-handle code to refactor
• Optional: Target lang (default: R; also applies to Python, TypeScript, Rust)

Steps

Step 1: Identify Trust Boundaries

Map where external data enters system. These are spots that need check:

• Public API functions (exported functions in R package)
• User-facing params
• File I/O (reading configs, data files, user uploads)
• Network responses (API calls, DB queries)
• Env vars and system config

Internal helper functions called only by your own checked code usually do not need dup check.

Got: List of entry points where untrusted data crosses into your code.

If fail: Edges unclear? Trace back from errors in logs or bug reports to find where bad data first entered.

Step 2: Add Guard Clauses at Entry Points

Check inputs at top of each public function, before any work starts.

R (base):

calculate_summary <- function(data, method = c("mean", "median", "trim"), trim_pct = 0.1) {
  # Guard: type check
  if (!is.data.frame(data)) {
    stop("'data' must be a data frame, not ", class(data)[[1]], call. = FALSE)
  }
  # Guard: non-empty
  if (nrow(data) == 0L) {
    stop("'data' must have at least one row", call. = FALSE)
  }
  # Guard: argument matching
  method <- match.arg(method)
  # Guard: range check
  if (!is.numeric(trim_pct) || trim_pct < 0 || trim_pct > 0.5) {
    stop("'trim_pct' must be a number between 0 and 0.5, got: ", trim_pct, call. = FALSE)
  }
  # --- All guards passed, begin real work ---
  # ...
}

R (rlang/cli — preferred for packages):

calculate_summary <- function(data, method = c("mean", "median", "trim"), trim_pct = 0.1) {
  rlang::check_required(data)
  if (!is.data.frame(data)) {
    cli::cli_abort("{.arg data} must be a data frame, not {.cls {class(data)}}.")
  }
  if (nrow(data) == 0L) {
    cli::cli_abort("{.arg data} must have at least one row.")
  }
  method <- rlang::arg_match(method)
  if (!is.numeric(trim_pct) || trim_pct < 0 || trim_pct > 0.5) {
    cli::cli_abort("{.arg trim_pct} must be between 0 and 0.5, not {.val {trim_pct}}.")
  }
  # ...
}

General (TypeScript):

function calculateSummary(data: DataFrame, method: Method, trimPct: number): Summary {
  if (data.rows.length === 0) {
    throw new Error(`data must have at least one row`);
  }
  if (trimPct < 0 || trimPct > 0.5) {
    throw new RangeError(`trimPct must be between 0 and 0.5, got: ${trimPct}`);
  }
  // ...
}

Got: Every public function opens with guard clauses that reject bad input before any side effects or compute.

If fail: Check logic gets long (>15 lines of guards)? Pull validate_* helper or use stopifnot() for simple type asserts.

Step 3: Write Meaningful Error Messages

Every error msg should answer four questions:

1. What failed — which param or op
2. Where — function name or context (auto with cli::cli_abort)
3. Why — what expected vs what got
4. How to fix — when fix not obvious

Good messages:

# What + Why (expected vs. actual)
stop("'n' must be a positive integer, got: ", n, call. = FALSE)

# What + Why + How to fix
cli::cli_abort(c(
  "{.arg config_path} does not exist: {.file {config_path}}",
  "i" = "Create it with {.run create_config({.file {config_path}})}."
))

# What + context
cli::cli_abort(c(
  "Column {.val {col_name}} not found in {.arg data}.",
  "i" = "Available columns: {.val {names(data)}}"
))

Bad messages:

stop("Error")                    # What failed? No idea
stop("Invalid input")           # Which input? What's wrong with it?
stop(paste("Error in step", i)) # No actionable information

Got: Error msgs self-doc — dev seeing error first time can diagnose and fix without read source code.

If fail: Review three most recent bug reports. Any need read source code to grasp? Their error msgs need fix.

Step 4: Prefer stop() Over warning()

Use stop() (or cli::cli_abort()) when function cannot make right result. Use warning() only when function can still make meaningful result but caller should know about worry.

Rule of thumb: User could silent get wrong answer? That is stop(), not warning().

# CORRECT: stop when result would be wrong
read_config <- function(path) {
  if (!file.exists(path)) {
    stop("Config file not found: ", path, call. = FALSE)
  }
  yaml::read_yaml(path)
}

# CORRECT: warn when result is still usable
summarize_data <- function(data) {
  if (any(is.na(data$value))) {
    warning(sum(is.na(data$value)), " NA values dropped from 'value' column", call. = FALSE)
    data <- data[!is.na(data$value), ]
  }
  # proceed with valid data
}

Got: stop() used for conds that would make wrong results; warning() reserved for degraded-but-valid outcomes.

If fail: Audit existing warning() calls. Function returns nonsense after warning? Change to stop().

Step 5: Use Assertions for Internal Invariants

For conds that "should never happen" in right code, use assertions. These catch programmer errors during dev:

# R: stopifnot for internal invariants
process_chunk <- function(chunk, total_size) {
  stopifnot(
    is.list(chunk),
    length(chunk) > 0,
    total_size > 0
  )
  # ...
}

# R: explicit assertion with context
merge_results <- function(left, right) {
  if (ncol(left) != ncol(right)) {
    stop("Internal error: column count mismatch (", ncol(left), " vs ", ncol(right),
         "). This is a bug — please report it.", call. = FALSE)
  }
  # ...
}

Got: Internal invariants asserted so bugs surface fast at violation site, not three function calls later with cryptic error.

If fail: stopifnot() msgs too cryptic? Switch to clear if/stop with context.

Step 6: Refactor Anti-Patterns

Spot and fix these common anti-patterns:

Anti-pattern 1: Empty tryCatch (swallow errors)

# BEFORE: Error silently disappears
result <- tryCatch(
  parse_data(input),
  error = function(e) NULL
)

# AFTER: Log, re-throw, or return a typed error
result <- tryCatch(
  parse_data(input),
  error = function(e) {
    cli::cli_abort("Failed to parse input: {e$message}", parent = e)
  }
)

Anti-pattern 2: Default values mask bad input

# BEFORE: Caller never knows their input was ignored
process <- function(x = 10) {
  if (!is.numeric(x)) x <- 10  # silently replaces bad input
  x * 2
}

# AFTER: Tell the caller about the problem
process <- function(x = 10) {
  if (!is.numeric(x)) {
    stop("'x' must be numeric, got ", class(x)[[1]], call. = FALSE)
  }
  x * 2
}

Anti-pattern 3: suppressWarnings as fix

# BEFORE: Hiding the symptom instead of fixing the cause
result <- suppressWarnings(as.numeric(user_input))

# AFTER: Validate explicitly, handle the expected case
if (!grepl("^-?\\d+\\.?\\d*$", user_input)) {
  stop("Expected a number, got: '", user_input, "'", call. = FALSE)
}
result <- as.numeric(user_input)

Anti-pattern 4: Catch-all exception handlers

# BEFORE: Every error treated the same
tryCatch(
  complex_operation(),
  error = function(e) message("Something went wrong")
)

# AFTER: Handle specific conditions, let unexpected ones propagate
tryCatch(
  complex_operation(),
  custom_validation_error = function(e) {
    cli::cli_warn("Validation issue: {e$message}")
    fallback_value
  }
  # Unexpected errors propagate naturally
)

Got: Anti-patterns swapped with clear check or specific error handle.

If fail: Remove tryCatch causes cascading fails? Upstream code has check gap. Fix source, not symptom.

Step 7: Validate the Fail-Early Refactoring

Run test suite to confirm error paths work right:

# Verify error messages are triggered
testthat::expect_error(calculate_summary("not_a_df"), "must be a data frame")
testthat::expect_error(calculate_summary(data.frame()), "at least one row")
testthat::expect_error(calculate_summary(mtcars, trim_pct = 2), "between 0 and 0.5")

# Verify valid inputs still work
testthat::expect_no_error(calculate_summary(mtcars, method = "mean"))

# Run full test suite
Rscript -e "devtools::test()"

Got: All tests pass. Error-path tests confirm bad input fires expected error msg.

If fail: Existing tests leaned on silent fails (e.g., returning NULL on bad input)? Update them to expect new error.

Validation

• Every public function checks its inputs before doing work
• Error msgs answer: what failed, where, why, how to fix
• stop() used for conds that make wrong results
• warning() used only for degraded-but-valid outcomes
• No empty tryCatch blocks that swallow errors silent
• No suppressWarnings() used as swap for proper check
• No default values that silent mask bad input
• Internal invariants use stopifnot() or clear assertions
• Error-path tests exist for each check guard
• Test suite passes after refactor

Pitfalls

• Check too deep: Check at trust edges (public API), not in every internal helper. Over-check adds noise and hurts speed.
• Error msgs with no context: "Invalid input" forces caller to guess. Always add param name, expected type/range, and actual value got.
• Use warning() when you mean stop(): Function returns garbage after warning? Caller gets wrong answer silent. Use stop() and let caller pick how to handle.
• Swallow errors in tryCatch: tryCatch(..., error = function(e) NULL) hides bugs. If you must catch, log or re-throw with added context.
• Forget call. = FALSE: In R, stop("msg") adds call by default, which is noisy for end users. Use call. = FALSE in user-facing functions. cli::cli_abort() does this auto.
• Check in tests instead of code: Tests verify behavior but do not guard prod callers. Check lives in function itself.
• Wrong R binary on hybrid systems: On WSL or Docker, Rscript may resolve to cross-platform wrapper instead of native R. Check with which Rscript && Rscript --version. Prefer native R binary (e.g., /usr/local/bin/Rscript on Linux/WSL) for reliability. See Setting Up Your Environment for R path config.

See Also

• write-testthat-tests - write tests that check error paths
• review-pull-request - review code for missing check and silent fails
• review-software-architecture - check error-handle strategy at system level
• create-skill - make new skills following agentskills.io standard
• security-audit-codebase - security-focused review that overlaps with input check