# Effect Errors Schema

> Use when modeling Effect errors, defects, Cause handling, Schema contracts, Schema.TaggedErrorClass, boundary decoding/encoding, RPC/tool/persistence validation, and typed failure recovery in Theseus.

- Skill: `theseus-run/effect-errors-schema` (Agent Skill)
- Install (CLI): `npx skillmds@latest add theseus-run/effect-errors-schema`
- Raw SKILL.md: https://api.skillmd.com/api/skills/theseus-run/effect-errors-schema/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: theseus-run (https://skillmd.com/u/theseus-run)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/theseus-run/effect-errors-schema

---


# Effect Errors And Schema

Use this skill for typed failures, schema contracts, and boundary normalization.

## Error Model

Use explicit domain errors. Expected failures stay in the Effect error channel. Defects are bugs, thrown exceptions, rejected promise defects, interrupts, or violated invariants.

Recovery is for expected external uncertainty: user input, network, filesystem, subprocesses, model providers, persistence, environment, and other foreign systems. Controlled internal protocol violations are defects.

Rules:

- Use `Data.TaggedError` for plain runtime/domain errors.
- Use `Schema.TaggedErrorClass` when the error must be schema-backed or serialized.
- Use `Effect.catchTag` / `Effect.catchTags` for known tagged failures.
- Use `Effect.catch` for all typed failures only when deliberately collapsing the union.
- Use `Effect.catchCause` when interrupts or defects must be inspected.
- Use `Cause.hasInterruptsOnly(cause)` to distinguish pure interruption from failure.
- Use `Effect.catchDefect` only for defect conversion at a boundary.
- Use `Effect.die`, thrown invariant errors, or equivalent hard failure for impossible internal states when types failed to prevent them.
- Do not use try/catch inside `Effect.gen` to catch Effect failures; they are not thrown.
- Do not throw expected failures.
- Do not recover from unsupported internal variants, impossible state transitions, or violated contracts with defaults, dropped events, or generic fallbacks.
- Do not erase error unions with `any`, `unknown`, or generic wrappers.

## Boundary Pattern

At every external boundary, normalize once:

- raw input -> Schema decode -> typed input
- foreign exception -> tagged typed failure
- domain failure -> explicit response or presentation
- defect -> logged/crashed/interrupted according to boundary policy

Examples of boundaries: tool calls, RPC handlers, SQLite calls, filesystem, subprocesses, model provider calls, WebSocket messages.

Inside the domain, keep typed values and typed failures. Do not repeatedly decode or stringify internal data. At important internal seams, validate or assert invariants and fail loudly when they are violated.

## Schema

Use Schema at external boundaries: tool inputs/outputs, RPC, persistence serialization, provider payloads, and config.

```typescript
import { Schema } from "effect"

export const UserId = Schema.String.pipe(Schema.brand("UserId"))
export type UserId = Schema.Schema.Type<typeof UserId>

export class RpcError extends Schema.TaggedErrorClass<RpcError>()("RpcError", {
  code: Schema.String,
  message: Schema.String,
}) {}
```

Rules:

- Use `Schema.Struct`, `Schema.Union`, `Schema.Literal`, and `Schema.Literals` for wire contracts.
- Use `Schema.optional(...)` for optional fields in this repo.
- Use branded schemas for IDs that cross service/package boundaries.
- Decode unknown inputs with `Schema.decodeUnknownEffect(schema)(raw)` when failures should stay typed.
- Keep schemas near the boundary they protect unless they are shared API contracts.
- Put JSON parse/stringify for protocol, provider, RPC, and persistence data behind schema-backed boundary helpers when practical. Raw JSON is acceptable for tests, debug output, or truly opaque passthrough data.
- Keep raw `Record<string, unknown>` at ingress or opaque passthrough boundaries. Domain code should receive decoded schemas or explicit extension points.
- Prefer narrow schemas for commands and events. Avoid `Schema.Unknown` except for explicitly open extension points.

## Checks

- Is the failure expected and recoverable, or is it a defect?
- Does the boundary serialize or persist this error?
- Are parse failures kept typed until the boundary handles them?
- Are `_tag` values globally safe where pattern matching crosses modules?
- Is this recovery handling external uncertainty, or is it hiding a broken internal contract?