ErrorReporter

Defines the runtime property key used to attach extra key/value metadata to an object error report.

When to use

Use to attach domain metadata to object errors so reporter callbacks receive it with the reported failure.

Details

Set error[ErrorReporter.attributes] to a record of metadata that should be forwarded to reporters alongside the error.

See

• ignore for suppressing reports for expected object errors
• severity for overriding reporter severity
• getAttributes for reading the metadata stored under this key
• Reportable for the annotation contract recognized on object errors

declare const attributes: "~effect/ErrorReporter/attributes"

import { Data, ErrorReporter } from "effect"

class PaymentError extends Data.TaggedError("PaymentError")<{
  readonly orderId: string
}> {
  readonly [ErrorReporter.attributes] = {
    orderId: this.orderId
  }
}

ErrorReporter.getAttributes(new PaymentError({ orderId: "order-123" })) // => { orderId: "order-123" }

Defines the string property key used to attach extra key/value metadata to an object error report.

When to use

Use to type the property key that attaches metadata to object error reports.

Details

Reporters receive these attributes alongside the error, making it easy to include contextual information such as user IDs, request IDs, or other domain-specific debugging data.

type attributes = "~effect/ErrorReporter/attributes"

Reads the ErrorReporter.attributes annotation from an error object, returning an empty record when unset.

When to use

Use to inspect the attributes that reporter callbacks will receive for an object error.

Details

Returns the value stored under ErrorReporter.attributes, or the module's shared empty record when the annotation is absent.

Gotchas

The annotation value is returned as-is; this helper does not validate or clone it.

See

• attributes for the annotation key used to attach metadata
• Reportable for the annotation properties recognized on object errors

declare function getAttributes(error: object): ReadonlyRecord<string, unknown>

Reads the ErrorReporter.severity annotation from an error object, falling back to "Info" when the annotation is unset or invalid.

When to use

Use to inspect the severity that reporter callbacks will receive for an object error.

See

• severity for the annotation key used to override severity
• Reportable for the annotation properties recognized on object errors

declare function getSeverity(error: object): Severity

Defines the runtime property key used to mark an object error as ignored by error reporting.

When to use

Use to suppress reporting for expected object errors, such as HTTP 404 responses.

Details

Set error[ErrorReporter.ignore] to true to prevent the error from being forwarded to reporters. This is useful for expected failures such as HTTP 404 responses.

See

• isIgnored for checking whether a value carries this annotation
• Reportable for the annotation contract recognized on object errors

declare const ignore: "~effect/ErrorReporter/ignore"

import { Data, ErrorReporter } from "effect"

class NotFoundError extends Data.TaggedError("NotFoundError")<{}> {
  readonly [ErrorReporter.ignore] = true
}

ErrorReporter.isIgnored(new NotFoundError()) // => true

Defines the string property key used to mark an object error as ignored by error reporting.

When to use

Use to type the property key that suppresses reporting for expected object errors.

Details

Set this property to true on an error class or object error to prevent it from being forwarded to reporters. This is useful for expected failures such as HTTP 404 responses.

type ignore = "~effect/ErrorReporter/ignore"

Interface that object errors can implement to control reporting behavior.

When to use

Use as the annotation contract for object errors that customize how error reporting handles them.

Details

All three annotation properties are optional: [ErrorReporter.ignore] prevents reporting when set to true, [ErrorReporter.severity] overrides the default "Info" severity, and [ErrorReporter.attributes] adds extra key/value pairs forwarded to reporters. The global Error interface is augmented with Reportable, so these properties are available on Error instances at the type level.

See

• ignore for the runtime annotation key that suppresses reports
• severity for the runtime annotation key that overrides severity
• attributes for the runtime annotation key that attaches reporter metadata

interface Reportable {
  readonly "~effect/ErrorReporter/attributes"?: ReadonlyRecord<string, unknown>;
  readonly "~effect/ErrorReporter/ignore"?: boolean;
  readonly "~effect/ErrorReporter/severity"?: Severity;
}

Defines the runtime property key used to override the severity level of an object error.

When to use

Use to annotate object errors with the severity reporter callbacks should receive.

Details

Set error[ErrorReporter.severity] to a valid LogLevel.Severity value. Missing or invalid values fall back to "Info".

See

• getSeverity for reading the severity stored under this key
• Reportable for the annotation contract recognized on object errors

declare const severity: "~effect/ErrorReporter/severity"

import { Data, ErrorReporter } from "effect"

class DeprecationWarning extends Data.TaggedError("DeprecationWarning")<{}> {
  readonly [ErrorReporter.severity] = "Warn" as const
}

ErrorReporter.getSeverity(new DeprecationWarning()) // => "Warn"

Defines the string property key used to override the severity level of an object error.

When to use

Use to type the property key that overrides the reporting severity for object errors.

Details

When set to a valid LogLevel.Severity, the reporter callback receives this value as severity. Missing or invalid values fall back to "Info".

type severity = "~effect/ErrorReporter/severity"

Creates an ErrorReporter from a callback.

When to use

Use to define how reported failures are forwarded to a logging, monitoring, or error-tracking backend.

Details

The returned reporter automatically deduplicates causes and individual errors (the same object is never reported twice), skips interruptions, and resolves the ignore, severity, and attributes annotations on each error before invoking your callback.

See

• layer for registering reporters in the environment
• report for manually reporting a Cause

declare function make(report: (options: {
  readonly attributes: ReadonlyRecord<string, unknown>;
  readonly cause: Cause<unknown>;
  readonly error: Error;
  readonly fiber: Fiber<unknown, unknown>;
  readonly severity: Severity;
  readonly timestamp: bigint;
}) => void): ErrorReporter

import { Effect, ErrorReporter } from "effect"

const reports: Array<{ message: string; severity: string; attributes: object }> = []
const reporter = ErrorReporter.make(({ error, severity, attributes }) => {
  reports.push({ message: error.message, severity, attributes })
})

const program = Effect.fail(new Error("boom")).pipe(
  Effect.withErrorReporting,
  Effect.provide(ErrorReporter.layer([reporter])),
  Effect.exit
)

await Effect.runPromise(program)
reports // => [{ message: "boom", severity: "Info", attributes: {} }]

Creates a Layer that registers one or more ErrorReporters.

When to use

Use to provide one or more error reporters to effects that perform error reporting.

Details

Reporters can be plain ErrorReporter values or effectful Effect<ErrorReporter> values that are resolved when the layer is built. By default the provided reporters replace any previously registered reporters. Set mergeWithExisting: true to add them alongside existing ones.

See

• make for creating an ErrorReporter from a callback
• CurrentErrorReporters for low-level access to the current reporters

declare function layer<Reporters extends readonly Array<ErrorReporter | Effect<ErrorReporter, any, any>>>(reporters: Reporters, options?: {
  readonly mergeWithExisting?: boolean;
}): Layer<never, Reporters extends readonly [] ? never : Error<Reporters[number]>, Exclude<Reporters extends readonly [] ? never : Services<Reporters[number]>, Scope>>

import { Effect, ErrorReporter } from "effect"

const reports: Array<string> = []
const firstReporter = ErrorReporter.make(({ error, severity }) => {
  reports.push(`[${severity}] ${error.message}`)
})
const secondReporter = ErrorReporter.make(({ error, severity }) => {
  reports.push(`${severity}: ${error.message}`)
})

// Replace all existing reporters
const ReporterLayer = ErrorReporter.layer([
  firstReporter,
  secondReporter
])

// Add to existing reporters instead of replacing
const ReporterMerged = ErrorReporter.layer(
  [secondReporter],
  { mergeWithExisting: true }
)

const program = Effect.fail("boom").pipe(
  Effect.withErrorReporting,
  Effect.provide(ReporterLayer),
  Effect.exit
)

await Effect.runPromise(program)
reports // => ["[Info] boom", "Info: boom"]

Runs all registered error reporters on the current fiber for a Cause.

When to use

Use to report a failure for observability without failing the current fiber.

declare function report<E>(cause: Cause<E>): Effect<void>

import { Cause, Effect, ErrorReporter } from "effect"

const messages: Array<string> = []
const program = Effect.gen(function*() {
  const cause = Cause.fail("something went wrong")
  yield* ErrorReporter.report(cause)
  return "fallback value"
})

const reporter = ErrorReporter.make(({ error }) => messages.push(error.message))
const output = await Effect.runPromise(
  Effect.provide(program, ErrorReporter.layer([reporter]))
)
messages // => ["something went wrong"]
output // => "fallback value"

Returns true if the given value has the ErrorReporter.ignore annotation set to true.

When to use

Use to check whether an error value is annotated to be skipped before forwarding it to error reporting code.

See

• ignore for the annotation key this predicate reads

declare function isIgnored(u: unknown): boolean

Context reference that holds the set of active error reporters for the current fiber. Defaults to an empty set (no reporting).

When to use

Use when you need to read or replace the current set of error reporters directly.

declare const CurrentErrorReporters: Context.Reference<ReadonlySet<ErrorReporter>>

An ErrorReporter receives reported failures and forwards them to an external system such as a logging service or error tracker.

When to use

Use as the interface for custom reporters that forward reported Effect failures to logging, monitoring, or error-tracking systems.

Details

Reporting is triggered by Effect.withErrorReporting, ErrorReporter.report, or built-in boundaries in the HTTP and RPC server modules. Use make to create a reporter; it handles deduplication and per-error annotation extraction automatically.

See

• make for creating an ErrorReporter from a callback
• layer for registering reporters in the environment
• report for manually reporting a Cause
• Effect.withErrorReporting for reporting failures from an effect

interface ErrorReporter {
  readonly "~effect/ErrorReporter": "~effect/ErrorReporter";
  report(options: {
    readonly cause: Cause<unknown>;
    readonly fiber: Fiber<unknown, unknown>;
    readonly timestamp: bigint;
  }): void;
}

Runtime type identifier attached to ErrorReporter values.

Details

This marker is part of the runtime representation of ErrorReporter implementations. Most code should create reporters with make and register them with layer.

declare const TypeId: "~effect/ErrorReporter"

String literal type used as the runtime type identifier for ErrorReporter values.

When to use

Use to refer to the runtime type identifier type in low-level integrations.

type TypeId = "~effect/ErrorReporter"