Effect CommunityEC
Effect Community•2mo ago•
2 replies
Igor Gassmann

Understanding Effect's Error Model: RuntimeException and UnknownException

I've been trying to understand Effect's error model in depth, but I'm confused about some of its primitives.

My current understanding is that Effect has two main categories of errors:

1. Expected Errors (Typed Errors/Failures): Appear in the error channel. Are recoverable.
2. Unexpected Errors (Defects): NOT in the error channel. NOT recoverable.

Where I get confused:

---

RuntimeException appears to be created by Effect.dieMessage() and becomes a defect:

Questions:
- Is RuntimeException only ever used for defects?
- Its JSDoc says that it "is used for errors that occur at runtime but are still considered recoverable or typed." Does this mean that RuntimeException can be used as an expected error as well?
- Is there a use case where I would want to create a RuntimeException directly?

---

UnknownException (which is getting renamed to UnknownError in Effect 4.0) seems to appear in two different contexts:

As a typed error (in E):
const effect = Effect.tryPromise(() => fetch(url))
// Type: Effect<Response, UnknownException, never>


As a defect (outside E):
const effect = Effect.sync(() => { throw new Error("Oops") })
// Type: Effect<void, never, never> - throws become defects


Questions:
- Why is UnknownException used in both contexts?
- Why does it exist in addition to RuntimeException?
- Is there a use case where I would want to create a UnknownException directly?

---

I noticed @effect/ai defines its own UnknownError as part of AiError. This is a typed error said to be used as a "catch-all for unexpected runtime errors" within the AI domain.

Questions:
- Is this a recommended pattern for application-level or library-level error modeling?
- How does this relate to Effect's built-in UnknownException (which is getting renamed to UnknownError in Effect 4.0)? Should I use this pattern instead of relying on UnknownException?
Was this page helpful?