PlatformErrorTagged error used by platform APIs to report either invalid arguments or system-level failures.
When to use
Use as the shared error type for platform APIs that expose invalid arguments
and host or operating-system failures through a single Effect error
channel.
Details
The reason field contains the underlying BadArgument or SystemError.
When that reason has a cause, the cause is preserved on the wrapper.
export class class PlatformErrorclass PlatformError {
message: string;
name: string;
stack: string;
cause: unknown;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
_tag: Tag;
reason: BadArgument | SystemError;
}
Tagged error used by platform APIs to report either invalid arguments or
system-level failures.
When to use
Use as the shared error type for platform APIs that expose invalid arguments
and host or operating-system failures through a single Effect error
channel.
Details
The reason field contains the underlying BadArgument or SystemError.
When that reason has a cause, the cause is preserved on the wrapper.
PlatformError extends import DataData.const TaggedError: <Tag extends string>(
tag: Tag
) => new <A extends Record<string, any> = {}>(
args: Types.VoidIfEmpty<{
readonly [P in keyof A as P extends "_tag"
? never
: P]: A[P]
}>
) => Cause.YieldableError & {
readonly _tag: Tag
} & Readonly<A>
Creates a tagged error class with a _tag discriminator.
When to use
Use when you need domain errors with discriminated-union handling.
Details
Like
Error
, but instances also carry a readonly _tag property,
enabling Effect.catchTag and Effect.catchTags for tag-based recovery.
The _tag is excluded from the constructor argument. Yielding an instance
inside Effect.gen fails the effect with this error.
Example (Recovering by tag)
import { Data, Effect } from "effect"
class NotFound extends Data.TaggedError("NotFound")<{
readonly resource: string
}> {}
class Forbidden extends Data.TaggedError("Forbidden")<{
readonly reason: string
}> {}
const program = Effect.gen(function*() {
return yield* new NotFound({ resource: "/users/42" })
})
const recovered = program.pipe(
Effect.catchTag("NotFound", (e) =>
Effect.succeed(`missing: ${e.resource}`))
)
TaggedError("PlatformError")<{
reason: BadArgument | SystemErrorreason: class BadArgumentclass BadArgument {
message: string;
name: string;
stack: string;
cause: unknown;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
_tag: Tag;
module: string;
method: string;
description: string | undefined;
}
Error data for an invalid argument passed to a platform API.
When to use
Use when you need to model caller input rejected before a platform operation
runs, including invalid-argument reason data.
Details
The error records the module and method that rejected the argument, with an
optional description and cause. It is usually wrapped in PlatformError.
BadArgument | class SystemErrorclass SystemError {
message: string;
name: string;
stack: string;
cause: unknown;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
_tag: SystemErrorTag;
module: string;
method: string;
description: string | undefined;
syscall: string | undefined;
pathOrDescriptor: string | number | undefined;
}
Error data for a platform or system operation failure.
When to use
Use when you need normalized reason data for a platform or system operation
failure, including the operation details.
Details
The error records a normalized _tag, the module and method that failed,
and optional details such as the syscall, path or descriptor, description,
and original cause. It is usually wrapped in PlatformError.
SystemError
}> {
constructor(reason: BadArgument | SystemErrorreason: class BadArgumentclass BadArgument {
message: string;
name: string;
stack: string;
cause: unknown;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
_tag: Tag;
module: string;
method: string;
description: string | undefined;
}
Error data for an invalid argument passed to a platform API.
When to use
Use when you need to model caller input rejected before a platform operation
runs, including invalid-argument reason data.
Details
The error records the module and method that rejected the argument, with an
optional description and cause. It is usually wrapped in PlatformError.
BadArgument | class SystemErrorclass SystemError {
message: string;
name: string;
stack: string;
cause: unknown;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
_tag: SystemErrorTag;
module: string;
method: string;
description: string | undefined;
syscall: string | undefined;
pathOrDescriptor: string | number | undefined;
}
Error data for a platform or system operation failure.
When to use
Use when you need normalized reason data for a platform or system operation
failure, including the operation details.
Details
The error records a normalized _tag, the module and method that failed,
and optional details such as the syscall, path or descriptor, description,
and original cause. It is usually wrapped in PlatformError.
SystemError) {
if ("cause" in reason: BadArgument | SystemErrorreason) {
super({ reason: BadArgument | SystemErrorreason, cause: unknowncause: reason: BadArgument | SystemErrorreason.Error.cause?: unknowncause } as any)
} else {
super({ reason: BadArgument | SystemErrorreason })
}
}
/**
* Marks this value as a platform error wrapper for runtime guards.
*
* **When to use**
*
* Use to identify `PlatformError` values through their runtime type marker.
*
* @since 4.0.0
*/
readonly [const TypeId: "~effect/platform/PlatformError"TypeId]: typeof const TypeId: "~effect/platform/PlatformError"TypeId = const TypeId: "~effect/platform/PlatformError"TypeId
override get PlatformError.message: stringmessage(): string {
return this.reason: BadArgument | SystemErrorreason.message: stringFormats the module, method, and optional description that rejected the argument.
When to use
Use to read the formatted error message for a rejected platform argument.
Formats the normalized system error tag with operation and path details.
When to use
Use to read the formatted error message for a normalized system failure.
message
}
}