error management

Error Management in Effect

Overview

Effect distinguishes between two types of failures:

1. Expected Errors (Recoverable) - Represented in the Error type parameter, tracked at compile time
2. Defects (Unexpected/Unrecoverable) - Runtime exceptions, bugs, not in type signature

Effect<Success, Error, Requirements>;
//              ^^^^^ Expected errors live here

Creating Typed Errors

Using Schema.TaggedError (Recommended)

import { Schema, Effect } from "effect";

class UserNotFound extends Schema.TaggedError<UserNotFound>()("UserNotFound", { userId: Schema.String }) {}

// Note: Schema.Unknown is semantically correct here because `cause` captures
// arbitrary caught exceptions whose type is genuinely unknown at the domain level.
// This is NOT type weakening - JavaScript exceptions can be any value.
class NetworkError extends Schema.TaggedError<NetworkError>()("NetworkError", { cause: Schema.Unknown }) {}

const getUser = (id: string): Effect.Effect<User, UserNotFound | NetworkError> =>
  Effect.gen(function* () {
    // ...implementation
    return yield* Effect.fail(new UserNotFound({ userId: id }));
  });

Using Effect.fail

const divide = (a: number, b: number) => (b === 0 ? Effect.fail(new DivisionByZero()) : Effect.succeed(a / b));

Catching and Recovering from Errors

catchAll - Catch All Errors

program.pipe(Effect.catchAll((error) => Effect.succeed("fallback value")));

catchTag - Catch Specific Error by Tag

const program = getUser(id).pipe(
  Effect.catchTag("UserNotFound", (error) => Effect.succeed(defaultUser)),
  Effect.catchTag("NetworkError", (error) => Effect.retry(Schedule.exponential("1 second"))),
);

catchTags - Handle Multiple Error Types

const program = getUser(id).pipe(
  Effect.catchTags({
    UserNotFound: (error) => Effect.succeed(defaultUser),
    NetworkError: (error) => Effect.fail(new ServiceUnavailable()),
  }),
);

orElse - Provide Fallback Effect

const primary = fetchFromPrimary();
const fallback = fetchFromBackup();

const resilient = primary.pipe(Effect.orElse(() => fallback));

orElseSucceed - Provide Fallback Value

const program = fetchConfig().pipe(Effect.orElseSucceed(() => defaultConfig));

Transforming Errors

mapError - Transform Error Type

const program = rawApiCall().pipe(Effect.mapError((error) => new ApiError({ cause: error })));

mapBoth - Transform Both Success and Error

const program = effect.pipe(
  Effect.mapBoth({
    onError: (e) => new WrappedError({ cause: e }),
    onSuccess: (a) => a.toUpperCase(),
  }),
);

Error Accumulation

When running multiple effects, collect all errors instead of failing fast:

Using Effect.all with mode: "either"

const results = yield * Effect.all([effect1, effect2, effect3], { mode: "either" });

Using Effect.partition

const [failures, successes] = yield * Effect.partition(items, (item) => processItem(item));

Using Effect.validate

const result = yield * Effect.validate([check1, check2, check3], { concurrency: "unbounded" });

Defects (Unexpected Errors)

Defects are bugs/unexpected failures not tracked in types:

const defect = Effect.die(new Error("Unexpected!"));

const program = effect.pipe(Effect.orDie);

const sandboxed = Effect.sandbox(program);

Cause - Full Error Information

The Cause type contains complete failure information:

import { Cause, Match } from "effect";

// In sandbox, you get full Cause - use Match for handling
const handled = Effect.sandbox(program).pipe(
  Effect.catchAll((cause) =>
    Match.value(cause).pipe(
      Match.when(Cause.isFailure, () => {
        // Expected error
        return Effect.succeed(fallback);
      }),
      Match.when(Cause.isDie, () => {
        // Defect - log and recover
        return Effect.succeed(fallback);
      }),
      Match.when(Cause.isInterrupt, () => {
        // Interruption
        return Effect.succeed(fallback);
      }),
      Match.orElse(() => Effect.succeed(fallback)),
    ),
  ),
);

Retrying

import { Schedule } from "effect";

const resilient = effect.pipe(
  Effect.retry(Schedule.exponential("100 millis").pipe(Schedule.jittered, Schedule.compose(Schedule.recurs(5)))),
);

// Retry with condition - use Match.tag for error type checking
const conditional = effect.pipe(
  Effect.retry({
    schedule: Schedule.recurs(3),
    while: (error) =>
      Match.value(error).pipe(
        Match.tag("NetworkError", () => true),
        Match.orElse(() => false),
      ),
  }),
);

Timeouts

const withTimeout = effect.pipe(Effect.timeout("5 seconds"));

const failOnTimeout = effect.pipe(
  Effect.timeoutFail({
    duration: "5 seconds",
    onTimeout: () => new TimeoutError(),
  }),
);

Error Matching Patterns

Using Effect.match

const result =
  yield *
  effect.pipe(
    Effect.match({
      onFailure: (error) => `Failed: ${error.message}`,
      onSuccess: (value) => `Success: ${value}`,
    }),
  );

Using Effect.matchEffect

const result =
  yield *
  effect.pipe(
    Effect.matchEffect({
      onFailure: (error) => logError(error).pipe(Effect.as("failed")),
      onSuccess: (value) => logSuccess(value).pipe(Effect.as("success")),
    }),
  );

Best Practices

1. Use TaggedError for all domain errors - Enables catchTag pattern matching
2. Keep error channel for recoverable errors - Use defects for bugs
3. Transform errors at boundaries - Map low-level errors to domain errors
4. Use typed errors generously - The compiler tracks them for free
5. Accumulate validation errors - Don't fail fast when validating
6. Only use Schema.Unknown for genuinely untyped values - The cause field on error types is the canonical example (caught JS exceptions can be any value). Never use Schema.Unknown or Schema.Any for fields whose shape you can describe - define proper schemas instead.

Additional Resources

For comprehensive error management documentation, consult ${CLAUDE_PLUGIN_ROOT}/references/llms-full.txt.

Search for these sections:

• "Expected Errors" for creating typed errors
• "Error Accumulation" for collecting multiple errors
• "Sandboxing" for handling defects
• "Retrying" for retry policies
• "Timing Out" for timeout patterns
• "Two Types of Errors" for error philosophy