Error Handling Patterns

How to recognize, signal, and handle errors effectively. Every error handling decision involves choosing how visible errors should be to callers and how much control callers should have over recovery.

Quick Reference

The Error Strategy Decision Table

The Recoverability Framework

Every error falls somewhere on the recoverability spectrum. The caller — not the author — determines whether an error is recoverable, because context decides what recovery means.

Can the caller realistically recover?
├── Yes → Use an explicit signaling technique
│         (checked exception, Result type, nullable return)
│         so the caller is forced to acknowledge the error.
└── No  → Use an implicit technique
          (unchecked exception, panic, assertion)
          so the error fails fast and loudly.

Key insight: The same error can be recoverable in one context and unrecoverable in another. An invalid phone number from user input is recoverable (show an error message). The same invalid phone number hard-coded in source code is a programming bug (fail fast).

Explicit vs. Implicit Signaling

Recoverability

Recoverable vs. Unrecoverable Errors

Not all errors are equal. Recoverable errors allow the system to continue meaningfully (retry, show a message, fall back). Unrecoverable errors indicate bugs or catastrophic failures where the only sensible response is to stop and surface the problem.

The Caller Determines Recoverability

Low-level code often can't know whether an error is recoverable. A phone number parser that encounters an invalid number doesn't know if the number came from user input (recoverable — ask for a correct one) or from a hard-coded constant (unrecoverable — programming bug). The function should assume the caller might want to recover, and signal the error explicitly.

Rules of thumb for when to assume recoverability:

• •We don't have exact knowledge of everywhere the function is called from
• •There's even a slim chance the code will be reused in a new context
• •The error is caused by something supplied to the function (not internal state)

Make Callers Aware

If callers aren't aware an error can happen, they won't write code to handle it. An unhandled error that a caller would have wanted to recover from leads to user-visible bugs or failures in business-critical logic. Use explicit signaling techniques to make errors part of the unmistakable contract.

Core Principles

Fail Fast

Signal errors as close to their source as possible. When code doesn't fail fast, the error manifests far from its origin — an invalid input accepted in one class may only cause a crash three layers deeper, requiring significant debugging effort to trace back.

Fail fast means: Throw an error or return a failure as soon as invalid state is detected. Don't carry invalid data through multiple function calls hoping it works out.

Fail Loudly

If an error can't be recovered from, make sure someone notices. The loudest approach is crashing the program. A weaker alternative is logging, though logs are often ignored. The goal: unrecoverable errors should never pass silently.

The robustness tension: Crashing a server because of one bad request is too aggressive. The solution is scope of recoverability — fail the individual request (log, monitor, alert), but keep the server running. Most server frameworks handle this by catching exceptions at the request boundary.

Checks and Assertions

When you can't make misuse impossible through the type system, use runtime checks to enforce contracts:

• •Precondition checks — Validate inputs and state before running logic. If the check fails, throw an error immediately (fail fast).
• •Postcondition checks — Validate results after running logic. Less common, but useful for complex transformations.
• •Assertions — Similar to checks, but typically compiled out in release builds. Use for conditions that "should never happen" during development. Leave assertions enabled in production unless performance demands otherwise.

Prefer compile-time enforcement. Making invalid states unrepresentable (private constructors, factory methods, dedicated types) is always better than runtime checks. When that's not possible, a runtime check that fails loudly beats documentation that goes unread.

Don't Hide Errors

Hiding errors is almost never a good idea. Common ways errors get hidden:

Suppressing exceptions is the worst form. Even logging the error doesn't help callers — they still believe the action succeeded. If you must catch an exception, re-signal the failure to the caller in some form.

Signaling Techniques

Checked Exceptions

The compiler forces the caller to acknowledge the error — either by catching it or declaring it in their own signature. Available in Java; other languages achieve similar explicitness through Result types.

Strengths: Errors can't be accidentally ignored. The API contract is explicit and compiler-enforced.

Weaknesses: Can become verbose when exceptions propagate through many layers, encouraging engineers to hide errors rather than handle them. Adding a new checked exception to a method is a breaking change for all callers.

Unchecked Exceptions

Callers are free to be completely unaware that an error might occur. Documentation may mention them, but nothing enforces handling.

Strengths: Cleaner code structure — error handling concentrates in a few layers rather than polluting every function. Doesn't force cascading signature changes.

Weaknesses: Callers can be completely oblivious to error scenarios. Undocumented exceptions turn catching them into a "whack-a-mole" game. Not handling an error happens by default rather than by active decision.

Result / Either Types

A return type that encapsulates either a success value or an error value. Built into Rust (Result<T, E>), Swift (Result), Kotlin (Result), and available as libraries in other languages (neverthrow for TypeScript, Vavr's Try for Java).

Strengths: Errors are values, not control flow. The type system enforces handling. Composable — results can be chained with map, flatMap, and similar operations. No invisible stack unwinding.

Weaknesses: Can be verbose in languages without built-in syntax support. Custom Result types rely on other engineers knowing the convention. Mixing with exception-based code creates inconsistency.

Nullable / Optional Return Types

Returning null (or Optional/Option) signals that a value couldn't be produced. With null safety enabled, the compiler forces the caller to check for null before using the value.

Strengths: Simple, well-understood. With null safety, provides explicit error signaling. Lightweight for "no value" scenarios.

Weaknesses: Conveys no information about why the value is absent. Without null safety, null returns are implicit and easily ignored. Null can be overloaded to mean multiple things (error vs. genuinely absent).

Magic Values / Error Codes

A special value within the normal return type signals an error (e.g., returning -1, or a status code). The caller must know to check for the magic value by reading documentation.

Strengths: Simple, zero overhead. Common in C and system-level APIs.

Weaknesses: Nothing in the type system prevents callers from using the magic value as a real value. Easy to forget. Implicit — a major source of bugs.

Recommendation: Avoid magic values in modern code. Use nullable types, Result types, or exceptions instead.

Outcome Return Types

Some functions don't return a value — they do something (send a message, write to disk). For these, an outcome return type (Boolean, enum, or status object) signals whether the action succeeded. This is explicit only if callers are forced to check the return value.

The ignorability problem: Unlike Result types, outcome return values can easily be ignored — callers can call sendMessage(channel, "hello") without checking the Boolean return. In languages that support it, use annotations like @CheckReturnValue (Java), [[nodiscard]] (C++), or #[must_use] (Rust) to generate compiler warnings when the return value is ignored.

Signaling Technique Comparison

The Debate: Unchecked vs. Explicit

Engineers disagree on whether recoverable errors should use unchecked exceptions or explicit techniques. Both sides have valid arguments.

Arguments for Unchecked Exceptions

Arguments for Explicit Techniques

Practical Guidance

What matters most is that your team agrees on a philosophy and applies it consistently. Half the codebase using explicit techniques and the other half using implicit is the worst outcome.

The modern consensus (2024-2026): The industry has shifted toward explicit, value-based error handling. Languages designed since 2010 (Rust, Go, Swift, Kotlin) all favor making errors visible in the type system. Even in traditionally exception-heavy ecosystems (TypeScript, Java), libraries like neverthrow, Effect-TS, and Vavr's Try are gaining adoption. The core insight driving this shift: errors are not exceptional — they are inevitable, and explicit handling produces more reliable code.

Wrapping Third-Party Errors

When your API uses a third-party library, propagating the library's exceptions leaks implementation details and creates coupling. If you later swap the library, all callers break.

The wrapping pattern:

1. •Create a domain-specific exception (e.g., PersonCatalogException instead of FileExistsException)
2. •Catch the library exception internally
3. •Wrap it in your domain exception, preserving the original as the cause
4. •Throw the domain exception from your public API

When to wrap:

• •Public APIs consumed by other teams or external users — always wrap
• •Internal APIs within the same team — wrap if the library might change
• •Private implementation code — wrapping adds overhead for little benefit

Exception messages matter. Combine the exception type, a descriptive message, and the original stack trace. These three pieces together make debugging significantly easier.

Error Handling in Special Contexts

Multithreaded / Async Code

Errors in background threads or async operations can silently disappear. Fire-and-forget patterns (execute() without checking the result) risk silent failures that kill threads and leak resources.

Key rules:

• •Always capture the Future/Promise result if the operation can fail
• •Register global exception handlers for uncaught thread exceptions
• •In async workflows, wrap exceptions into the Promise/CompletableFuture rather than throwing them — mixing promise-based and exception-based error handling creates confusing stack traces

Functional Error Handling (Try / Either)

The functional approach models every possible outcome as a type. A Try monad carries either a success value or a failure (exception), allowing callers to chain processing with map and flatMap without try-catch blocks.

Tension with OOP: Mixing functional error handling (Try, Either) with object-oriented exception throwing creates inconsistency. If part of the codebase uses Try and another part throws exceptions, the boundaries become confusing. Pick one approach per component and be consistent.

Modern Language-Specific Patterns

Go: Errors as Values

Go treats errors as ordinary values rather than special control flow. Functions return an error alongside their result, and callers check it explicitly. This makes error handling visible at every call site — nothing is implicit.

The error interface: Go's error is a simple interface with one method: Error() string. Any type implementing this interface is an error. This simplicity enables custom error types with additional context (error codes, metadata, nested causes).

Sentinel errors vs. custom types:

Error wrapping (fmt.Errorf with %w): Wrapping adds context as errors propagate up the call stack without losing the original cause. Each layer adds its own context: fmt.Errorf("loading user %d: %w", id, err) produces a chain like "loading user 42: querying database: connection refused".

Error inspection:

• •errors.Is(err, target) — checks if any error in the chain matches a sentinel value. Use for "is this a not-found error?" checks.
• •errors.As(err, &target) — checks if any error in the chain matches a type, and unwraps it. Use for "get me the validation details" checks.

Go's tradeoff: Explicit error checking at every call site produces verbose code (if err != nil appears frequently). The benefit is that no error path is hidden — every failure is visible in the code. The cost is boilerplate. This is a deliberate design choice: Go prioritizes clarity over brevity.

TypeScript: Discriminated Unions

TypeScript's type system enables errors-as-values through discriminated unions — a union type where each variant has a literal type (or kind) field that TypeScript can narrow on.

The pattern:

type Result<T> =
  | { ok: true; value: T }
  | { ok: false; error: ErrorDetail }

// Caller must check the discriminant before accessing the value
function getUser(id: string): Result<User> { ... }

const result = getUser("123");
if (result.ok) {
  result.value  // TypeScript knows this is User
} else {
  result.error  // TypeScript knows this is ErrorDetail
}

Why discriminated unions over thrown errors: TypeScript's throw is untyped — catch (e) gives you unknown, and nothing in the type system tells callers what a function might throw. Discriminated unions make error types explicit in the function signature, just like Rust's Result<T, E>.

Typed error variants: Discriminated unions shine when different errors need different handling:

type FetchError =
  | { type: "network"; retryable: true }
  | { type: "auth"; expired: boolean }
  | { type: "notFound" }

TypeScript's exhaustive switch on the type field ensures every variant is handled. Adding a new variant causes a compile error at every unhandled switch — the same benefit as checked exceptions, without the verbosity.

Libraries: neverthrow and Effect-TS provide Result types with map, flatMap, and railway-oriented composition, bringing Rust-style ergonomics to TypeScript.

Error Handling Antipatterns

Decision Tables

"Which error signaling technique should I use?"

"How do I know my error handling is wrong?"

Checklist

Before shipping error handling code:

• • Recoverability assessed: Each error classified as recoverable or not, from the caller's perspective
• • Explicit where needed: Recoverable errors use techniques that force caller awareness
• • No hidden errors: No default values, empty collections, or suppressed exceptions masking failures
• • Fail fast: Invalid state detected and signaled at the earliest point
• • Third-party errors wrapped: Public APIs don't leak library-specific exceptions
• • Async errors captured: No fire-and-forget patterns that silently swallow failures
• • Error messages useful: Type + message + stack trace provide enough context to debug
• • Team consistency: Error handling approach matches the rest of the codebase

See Also

• •software-tradeoffs — Error handling strategy comparison table, exception wrapping tradeoffs (see software-tradeoffs -> Error Handling: Exceptions vs. Alternatives)
• •code-quality-foundations — Reliability pillar, making code hard to misuse (see code-quality-foundations -> Make Code Hard to Misuse)
• •code-antipatterns — Surprise antipatterns from hidden errors (see code-antipatterns -> Surprise Antipatterns)
• •refactoring-patterns — Techniques for improving error handling in existing code (see refactoring-patterns -> When to Refactor)