Use when Effect error handling patterns including catchAll, catchTag, either, option, and typed errors. Use for handling expected errors in Effect applications.
Limited to specific tools
Additional assets for this skill
This skill is limited to using the following tools:
name: effect-error-handling description: Use when Effect error handling patterns including catchAll, catchTag, either, option, and typed errors. Use for handling expected errors in Effect applications. allowed-tools:
Master type-safe error handling in Effect applications. This skill covers expected errors, error recovery, selective error handling, and error transformations using Effect's error management operators.
Effect distinguishes between two types of failures:
import { Effect } from "effect"
// Expected error - tracked in type
interface ValidationError {
_tag: "ValidationError"
field: string
message: string
}
const validateEmail = (email: string): Effect.Effect<string, ValidationError, never> => {
if (!email.includes("@")) {
return Effect.fail({
_tag: "ValidationError",
field: "email",
message: "Invalid email format"
})
}
return Effect.succeed(email)
}
// Defect - throws, becomes unexpected failure
const riskyOperation = Effect.sync(() => {
throw new Error("Unexpected error") // This is a defect
})
// Proper way - expected error
const safeOperation = Effect.try({
try: () => {
// Code that might throw
return riskyParse(data)
},
catch: (error) => ({
_tag: "ParseError",
message: String(error)
})
})
Use tagged unions for error types to enable pattern matching:
import { Effect } from "effect"
// Define tagged error types
interface NotFoundError {
_tag: "NotFoundError"
id: string
}
interface UnauthorizedError {
_tag: "UnauthorizedError"
userId: string
}
interface NetworkError {
_tag: "NetworkError"
message: string
}
type AppError = NotFoundError | UnauthorizedError | NetworkError
// Functions returning typed errors
const fetchUser = (id: string): Effect.Effect<User, NotFoundError | NetworkError, never> => {
// Implementation
}
const authenticate = (token: string): Effect.Effect<User, UnauthorizedError | NetworkError, never> => {
// Implementation
}
Catches all expected errors and provides fallback:
import { Effect } from "effect"
const program = Effect.gen(function* () {
const user = yield* fetchUser("123")
return user
}).pipe(
Effect.catchAll((error) =>
Effect.succeed({ id: "default", name: "Guest" })
)
)
// Effect<User, never, never> - Error channel is now never
// With error inspection
const programWithLogging = Effect.gen(function* () {
const user = yield* fetchUser("123")
return user
}).pipe(
Effect.catchAll((error) => {
console.error("Error occurred:", error)
return Effect.succeed(defaultUser)
})
)
// Fallback to another effect
const programWithFallback = pipe(
fetchUser("123"),
Effect.catchAll(() => fetchUserFromCache("123"))
)
Catches errors by their _tag field:
import { Effect, pipe } from "effect"
const program = pipe(
fetchUser("123"),
Effect.catchTag("NotFoundError", (error) =>
Effect.succeed({ id: error.id, name: "Not Found" })
)
)
// Still can fail with NetworkError
// Handling multiple tags
const program2 = pipe(
authenticatedRequest(),
Effect.catchTag("UnauthorizedError", (error) =>
Effect.fail({ _tag: "LoginRequired" })
),
Effect.catchTag("NetworkError", (error) =>
retryRequest()
)
)
// Using Effect.gen with early return
const program3 = Effect.gen(function* () {
const result = yield* riskyOperation().pipe(
Effect.catchTag("TemporaryError", () =>
Effect.succeed(null)
)
)
return result
})
import { Effect, pipe } from "effect"
const program = pipe(
complexOperation(),
Effect.catchTags({
NotFoundError: (error) =>
Effect.succeed(defaultValue),
UnauthorizedError: (error) =>
Effect.fail({ _tag: "LoginRequired" }),
NetworkError: (error) =>
retryOperation()
})
)
// With different recovery strategies
const programWithStrategies = pipe(
processPayment(amount),
Effect.catchTags({
InsufficientFunds: (error) =>
Effect.fail({ _tag: "PaymentDeclined", reason: "insufficient-funds" }),
NetworkError: () =>
retryPayment(amount),
ValidationError: (error) =>
Effect.fail({ _tag: "InvalidPayment", field: error.field })
})
)
Catches errors that match a predicate:
import { Effect, pipe } from "effect"
const isRetryable = (error: AppError): boolean => {
return error._tag === "NetworkError" || error._tag === "TimeoutError"
}
const program = pipe(
fetchData(),
Effect.catchIf(isRetryable, (error) =>
retryFetchData()
)
)
// With type narrowing
const program2 = pipe(
operation(),
Effect.catchIf(
(error): error is NetworkError => error._tag === "NetworkError",
(error) => {
// TypeScript knows error is NetworkError here
console.log("Network error:", error.message)
return retry()
}
)
)
Catches errors and optionally handles them:
import { Effect, Option, pipe } from "effect"
const program = pipe(
fetchUser("123"),
Effect.catchSome((error) => {
if (error._tag === "NotFoundError") {
return Option.some(Effect.succeed(guestUser))
}
return Option.none() // Don't handle, propagate error
})
)
// Complex decision logic
const programWithDecision = pipe(
processRequest(request),
Effect.catchSome((error) => {
if (error._tag === "RateLimitError" && error.retryAfter < 1000) {
return Option.some(
Effect.sleep(error.retryAfter).pipe(
Effect.andThen(processRequest(request))
)
)
}
return Option.none()
})
)
Transforms an effect into one that cannot fail, wrapping result in Either:
import { Effect, Either } from "effect"
const program = Effect.gen(function* () {
const result = yield* fetchUser("123").pipe(Effect.either)
if (Either.isLeft(result)) {
// Handle error
console.error("Error:", result.left)
return null
} else {
// Handle success
return result.right
}
})
// Effect<User | null, never, never>
// Pattern matching on Either
const program2 = pipe(
fetchUser("123"),
Effect.either,
Effect.map(
Either.match({
onLeft: (error) => ({ success: false, error }),
onRight: (user) => ({ success: true, data: user })
})
)
)
Converts failures to None, success to Some:
import { Effect, Option } from "effect"
const program = Effect.gen(function* () {
const maybeUser = yield* fetchUser("123").pipe(Effect.option)
if (Option.isNone(maybeUser)) {
return guestUser
} else {
return maybeUser.value
}
})
// Effect<User, never, never>
// Using Option.match
const program2 = pipe(
fetchUser("123"),
Effect.option,
Effect.map(
Option.match({
onNone: () => "No user found",
onSome: (user) => `Found: ${user.name}`
})
)
)
import { Effect, pipe } from "effect"
interface DbError {
_tag: "DbError"
code: string
message: string
}
interface AppError {
_tag: "AppError"
message: string
context: string
}
const program = pipe(
queryDatabase(),
Effect.mapError((dbError: DbError): AppError => ({
_tag: "AppError",
message: dbError.message,
context: `Database operation failed: ${dbError.code}`
}))
)
// Enriching errors with context
const enrichError = <E extends { message: string }>(
context: string
) => (error: E) => ({
...error,
message: `${context}: ${error.message}`
})
const programWithContext = pipe(
fetchData(),
Effect.mapError(enrichError("Failed to fetch user data"))
)
Perform side effects when an error occurs without changing it:
import { Effect, pipe } from "effect"
const program = pipe(
processPayment(amount),
Effect.tapError((error) =>
Effect.sync(() => {
console.error("Payment failed:", error)
logToMonitoring(error)
})
),
Effect.tapError((error) =>
sendErrorNotification(error)
)
)
// Error still propagates after taps
Provide alternative effect on failure:
import { Effect, pipe } from "effect"
const program = pipe(
fetchFromPrimarySource(),
Effect.orElse(() => fetchFromSecondarySource())
)
// With error-specific fallbacks
const programWithCheck = pipe(
fetchData(),
Effect.orElse((error) => {
if (error._tag === "NetworkError") {
return fetchFromCache()
}
return Effect.fail(error)
})
)
// Multiple fallbacks
const programWithMultipleFallbacks = pipe(
fetchFromPrimary(),
Effect.orElse(() => fetchFromSecondary()),
Effect.orElse(() => fetchFromTertiary()),
Effect.orElse(() => Effect.succeed(defaultData))
)
import { Effect, Schedule, pipe } from "effect"
// Retry with schedule
const program = pipe(
fetchData(),
Effect.retry(Schedule.recurs(3)) // Retry up to 3 times
)
// Exponential backoff
const programWithBackoff = pipe(
fetchData(),
Effect.retry(
Schedule.exponential("100 millis", 2.0) // 100ms, 200ms, 400ms, ...
)
)
// Conditional retry
const programConditionalRetry = pipe(
fetchData(),
Effect.retry({
while: (error) => error._tag === "NetworkError",
schedule: Schedule.recurs(5)
})
)
import { Effect, pipe } from "effect"
const program = pipe(
complexOperation(),
Effect.catchTag("NotFoundError", () =>
Effect.succeed(defaultValue)
),
Effect.catchTag("NetworkError", () =>
retryOperation()
),
Effect.catchTag("UnauthorizedError", () =>
Effect.fail({ _tag: "LoginRequired" })
),
Effect.catchAll((unknownError) =>
Effect.sync(() => {
console.error("Unhandled error:", unknownError)
return fallbackValue
})
)
)
import { Effect, Array } from "effect"
interface ValidationError {
_tag: "ValidationError"
errors: string[]
}
const validateAll = (fields: string[]) =>
Effect.gen(function* () {
const results = yield* Effect.all(
fields.map(validateField),
{ mode: "either" } // Don't short-circuit on first error
)
const errors = results.filter(Either.isLeft)
if (errors.length > 0) {
return yield* Effect.fail({
_tag: "ValidationError",
errors: errors.map(e => e.left.message)
})
}
return results.map(r => r.right)
})
import { Effect, Cause, Exit, pipe } from "effect"
const program = pipe(
riskyOperation(),
Effect.catchAllCause((cause) => {
if (Cause.isFailure(cause)) {
// Expected error
const error = Cause.failureOption(cause)
return handleExpectedError(error)
} else if (Cause.isDie(cause)) {
// Defect (unexpected error)
const defect = Cause.dieOption(cause)
return handleDefect(defect)
} else {
// Interruption
return Effect.succeed(defaultValue)
}
})
)
Converts defects into the error channel for handling:
import { Effect, Cause, pipe } from "effect"
const program = pipe(
riskyOperation(),
Effect.sandbox,
Effect.catchAll((cause) => {
console.error("Failure cause:", cause)
return Effect.succeed(fallbackValue)
})
)
Use Tagged Error Types: Always tag errors with _tag for catchTag.
Keep Error Types Specific: Don't use generic Error. Define specific error types for each failure mode.
Handle Errors Close to Source: Catch errors where you have enough context to handle them properly.
Use catchTag Over catchAll: Prefer specific error handling to blanket catching.
Convert at Boundaries: Use either/option when interfacing with code that doesn't expect errors.
Log Before Catching: Use tapError to log before handling errors.
Don't Swallow Errors: Always handle errors meaningfully or propagate them.
Use Retry Strategically: Only retry transient failures, not all errors.
Enrich Errors with Context: Add context to errors as they propagate up.
Document Error Types: Clearly document what errors each function can produce.
Using catchAll Everywhere: Over-using catchAll hides error types. Use catchTag.
Not Tagging Errors: Without tags, you can't use catchTag effectively.
Swallowing Errors: Catching errors and returning success without proper handling.
Infinite Retry: Not limiting retries or checking error types before retrying.
Losing Error Information: Transforming errors without preserving important details.
Not Handling Defects: Forgetting that some operations can throw unexpectedly.
Wrong Error Boundaries: Catching errors too early or too late in the pipeline.
Type Widening: Losing specific error types by combining with catchAll too early.
Ignoring Error Channel: Not checking the E type parameter when composing effects.
Not Testing Error Paths: Only testing happy paths, not failure scenarios.
Use effect-error-handling when you need to: