ErrorReporter
Reports Effect failures to external code.
An ErrorReporter receives Cause values from Effect.withErrorReporting, manual report calls, or built-in reporting boundaries. It forwards each non-interruption error to a callback, so applications can send failures to logging, monitoring, or error-tracking systems. This module also includes layers for installing reporters and symbols for marking errors as ignored or attaching severity and attributes.
Annotations
attributes
Signature
declare const attributes: "~effect/ErrorReporter/attributes";attributes type
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.
Signature
type attributes = "~effect/ErrorReporter/attributes";getAttributes
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
attributesfor the annotation key used to attach metadataReportablefor the annotation properties recognized on object errors
Signature
declare function getAttributes(error: object): ReadonlyRecord<string, unknown>;getSeverity
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
severityfor the annotation key used to override severityReportablefor the annotation properties recognized on object errors
Signature
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
isIgnoredfor checking whether a value carries this annotationReportablefor the annotation contract recognized on object errors
Signature
declare const ignore: "~effect/ErrorReporter/ignore";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.
Signature
type ignore = "~effect/ErrorReporter/ignore";Reportable interface
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
ignorefor the runtime annotation key that suppresses reportsseverityfor the runtime annotation key that overrides severityattributesfor the runtime annotation key that attaches reporter metadata
Signature
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
getSeverityfor reading the severity stored under this keyReportablefor the annotation contract recognized on object errors
Signature
declare const severity: "~effect/ErrorReporter/severity";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".
Signature
type severity = "~effect/ErrorReporter/severity";Constructors
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
Signature
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;Layers
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
makefor creating anErrorReporterfrom a callbackCurrentErrorReportersfor low-level access to the current reporters
Signature
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>>Logging
Predicates
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
ignorefor the annotation key this predicate reads
Signature
declare function isIgnored(u: unknown): boolean;Services
CurrentErrorReporters
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.
Signature
declare const CurrentErrorReporters: Context.Reference<ReadonlySet<ErrorReporter>>;ErrorReporter interface
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
Signature
interface ErrorReporter {
readonly "~effect/ErrorReporter": "~effect/ErrorReporter";
report(options: {
readonly cause: Cause<unknown>;
readonly fiber: Fiber<unknown, unknown>;
readonly timestamp: bigint;
}): void;
}Type IDs
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.
Signature
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.
Signature
type TypeId = "~effect/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
ignorefor suppressing reports for expected object errorsseverityfor overriding reporter severitygetAttributesfor reading the metadata stored under this keyReportablefor the annotation contract recognized on object errors