error-management_skill

Overview

This skill explains how Effect models and handles failures, distinguishing typed recoverable errors from runtime defects. It shows how to create tagged domain errors, catch and transform errors, accumulate failures, and handle defects via sandboxing, retrying, and timeouts. The guidance focuses on practical APIs like Effect.fail, Effect.catchTag, Effect.mapError, Effect.retry, and Effect.sandbox.

How this skill works

Effect tracks expected, recoverable errors in the effect's Error type parameter and treats unexpected runtime failures as defects not included in the signature. You create typed domain errors with Schema.TaggedError or use Effect.fail for simple cases. Use catchTag/catchAll/orElse to recover, mapError/mapBoth to transform errors, and sandbox to surface full Cause information for handling defects. Retry, timeout, and accumulation primitives let you control retry policies, time-bound effects, and collect multiple errors.

When to use it

• When you need compile-time, typed domain errors instead of throwing exceptions
• When you want to match and recover from specific error types (catchTag)
• When you must retry transient failures or apply timeouts
• When collecting validation or parallel operation errors instead of failing fast
• When diagnosing or handling defects using sandboxed Cause information

Best practices

• Model domain errors with Schema.TaggedError so you can use catchTag and pattern matching
• Keep the error channel for recoverable failures; use defects for bugs and truly unexpected conditions
• Map low-level errors to domain errors at boundaries so callers see stable types
• Accumulate validation errors (Effect.validate or Effect.all with mode: 'either') rather than fail fast
• Use sandbox and Cause matching to distinguish expected errors, defects, and interrupts

Example use cases

• Return a typed UserNotFound error from a repository and recover with catchTag to supply a default user
• Retry network calls with an exponential jittered schedule and conditional retry only for NetworkError
• Transform raw API errors to ApiError with mapError before exposing them to higher layers
• Run parallel validations and collect all failures using Effect.validate for comprehensive feedback
• Sandbox a program to inspect Cause and log or recover from defects separately from expected errors