Source: repos/effect/packages/effect/src/Cause.ts, Exit.ts,
Effect.ts (fail, catch, catchTag, die), and
repos/effect/LLMS.md § Error handling. Refresh when the subtree moves.
This repo already has fail-closed typed errors. Effect's error channel maps onto those classes at the boundary. It does not replace them.
| Class | Codes (do not widen) |
|---|---|
AgentRequestError |
invalid-invocation, outside-invocation, request-closed, store-version-conflict |
AgentContractError |
document / event / elapsed bounds, handoff-required |
AgentStateError |
aborted, corrupt, idempotency-conflict, invalid-*, lifetime-mismatch, migration-*, reducer-failure, revision-*, store-closed, unavailable |
Observed<T> unavailable reasons (not-provided, unsupported-surface,
host-omitted, unauthenticated) stay a data union, not an Effect error.
- Succeed:
Effect.succeed(value),Effect.sync(() => value). - Typed fail, public or Effect-free class:
Effect.fail(new AgentRequestError('request-closed', message)). - Typed fail, framework-process class (dev seam / eval service, extends
YieldableFrameworkErrororYieldableCodedErrorfrompackages/agent-bundle/src/effect/errors.ts):return yield* new RuntimeGenerationStoreError('RUNTIME_GENERATION_CLOSED', message).Effect.fail(new RuntimeGenerationStoreError(...))is equally valid; do not churn call sites for style. - Defect (bug):
Effect.die(defect): not for expected fail-closed states. - Recover:
Effect.catch,Effect.catchTagwhen the error is tagged. None of our classes are tagged (Data.Error, notData.TaggedErrororSchema.TaggedError). Catch them withEffect.catch((error) => ...)andinstanceof/error.name/error.code. - Inspect after run:
Exit.isSuccess/isFailure, thenCause.squash,Cause.hasInterruptsOnly,Cause.hasFails,Cause.hasDies.
The Wave 3.5 brief defers Effect Schema. Do not convert Agent*Error to
Schema.TaggedError to unlock catchTag. Revisit only if a later wave
explicitly lifts the Schema deferral.
import { YieldableCodedError, YieldableFrameworkError } from '../effect/errors.ts';
export class ScriptPlaygroundFailure extends YieldableCodedError<ScriptPlaygroundFailureCode> {
constructor(code: ScriptPlaygroundFailureCode, message: string) {
super('ScriptPlaygroundFailure', code, message);
}
}
export class DevCoordinatorCloseError extends YieldableFrameworkError {
readonly failures: readonly DevCoordinatorCloseFailure[];
constructor(failures: readonly DevCoordinatorCloseFailure[]) {
super('DevCoordinator could not close every resource.');
this.name = 'DevCoordinatorCloseError';
this.failures = failures;
}
}The bases keep the Error / CodedError constructor shapes, so migrating
an existing class is the extends clause plus the import. They also keep
the plain-Error observable shape, JSON.stringify, stableJson,
{ ...error }, util.inspect, non-enumerable cause, which rc.117
Data.Error alone would change (its prototype toJSON spreads the
constructor fields; its [nodejs.util.inspect.custom] prints that instead
of the stack). Never extend Data.Error directly.
Stay on plain Error / CodedError when the class's declaration file is
reachable from any package.json export's types, exported or not; a
consumer's tsc follows the whole .d.ts graph, so McpSessionError
(reached from . / ./api through the dev types) stays plain even though
it is never exported, when it is reachable from an Effect-free entry
(agent-bundle/config, meta, rstest, test/browser, the CLI --help
path, the host MCP proxy), or when it ships inside an emitted artifact.
docs/effect-conventions.md § "Yieldable framework errors" lists the
current carve-outs; tests/public-api.test.ts ("keeps every public
declaration graph free of effect"), tests/emitted-artifact-effect-surface.test.ts,
and tests/cli.test.ts fail if one is crossed. Before migrating a class,
run pnpm build and that public-api test; if it reports the class's
.d.ts, the class is on a public graph and keeps its plain base.
packages/rsc-runtime/src/effect/boundary.ts:
Cause.hasInterruptsOnly→DOMExceptionAbortError(host cancellation).AgentRequestError/AgentContractErrorviainstanceof.AgentStateErrorviaerror.name(no./state/contractimport on the root graph).- Other
Errorrethrown; other values wrapped.
Callers of runPromise see the same types they see today.
try/catcharoundEffect.genconstruction. It catches nothing useful; handle errors in the channel.- Putting
unknownor globalErrorin the fail channel (unknownInEffectCatch,globalErrorInEffectFailure). - Swallowing interruption as a typed success. Cancellation is
AbortError.Stream.toReadableStream'sCause.squashis not that mapping, use the boundary helper. Effect.runPromisein a test to "see the error" whenEffect.exit+Causeis the assertion you want, still only through the boundary.- New public error codes without updating the authoring docs and the mapping
table in
docs/effect-conventions.md.
Effect 4.0.0 keeps the flat Cause contract. Concurrent cleanup failures
can accompany interruption, so use the package boundary's cause handling
instead of treating every cause containing an interrupt as interrupt-only.