effect-error-handling

Implement typed error handling in Effect v4 using Schema.TaggedError, catch combinators, and Cause inspection.

1|Updated Aug 24, 2026
One-click install
npx skills add https://github.com/lambdasolver2/opencode-effect-harness --skill effect-error-handling-lambdasolver2
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: effect-error-handling
Source: https://github.com/lambdasolver2/opencode-effect-harness/tree/main/packages/module-typescript/assets/skills/effect-error-handling
Command: npx skills add https://github.com/lambdasolver2/opencode-effect-harness --skill effect-error-handling-lambdasolver2

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Effect v4 renamed and restructured many error-handling APIs from v3, and mixing up error channels, defects, and the new flattened Cause model leads to untyped failures and broken recovery logic. This Skill provides authoritative v4 guidance so typed errors are modeled, caught, and recovered correctly. ## Core Features & Use Cases - v3-to-v4 API Migration Tables: Authoritative mappings for renamed catch combinators (catchAll to catch, catchSome to catchFilter), the flattened Cause structure, and error class renames from Exception to Error suffixes. - Error Class Design Guidance: Decision trees for choosing Schema.TaggedError, Schema.Error, or Data.TaggedError, plus patterns for reason unions, HTTP status annotations, and cause wrapping conventions. - Recovery Pattern Coverage: Examples for catchTag arrays, catchTags with orElse fallbacks, catchReason/catchReasons for nested reason unions, unwrapReason, catchEager, and yieldable errors in generators. - Use Case: When migrating an Effect v3 service that uses catchAll and recursive Cause trees, apply this Skill to rewrite handlers with v4 catch, catchTag arrays, and the flat reasons array while preserving type safety. ## Quick Start Ask the assistant to refactor an Effect service's error handling to Effect v4 using Schema.TaggedError classes and catchTag recovery.

Frequently Asked Questions about effect-error-handling

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create typed errors in Effect v4?

Use Schema.TaggedError to define error classes with a _tag discriminator and schema-validated fields, including a message field. For module-internal errors without serialization needs, Data.TaggedError is a lighter alternative, and Schema.Error suits custom discriminator fields.

What replaced Effect.catchAll in Effect v4?

Effect.catchAll was renamed to Effect.catch in v4, and catchAllCause became catchCause. The v4 catchTag also accepts an array of tags and an optional orElse fallback handler for unmatched errors.

How do I handle nested error reasons with catchReason in Effect v4?

Model each reason variant as its own TaggedError and compose them with Schema.Union in a parent error's reason field. Then use Effect.catchReason or catchReasons to handle specific variants, or unwrapReason to promote reasons into the error channel for catchTags.

When should I use defects instead of the error channel in Effect?

Use the typed error channel for caller-actionable business failures and public service contracts. Reserve defects via Effect.die or orDie for impossible branches, invariant violations, and adapter-internal failures no caller can recover from.

How did the Cause type change in Effect v4?

Cause is now a flat wrapper around a reasons array with only Fail, Die, and Interrupt variants, replacing the v3 recursive tree. Use Cause.findError, hasFails, and isFailReason instead of the removed failureOption and isFailure APIs.