Skip to content
Effect Days 2026 Get your ticket

PlatformError

Normalized errors for platform APIs.

Platform services such as file systems, terminals, and sockets use PlatformError to report host-level failures in a consistent shape. The wrapper records whether the problem came from an invalid argument or from the operating system, while preserving useful details such as the module, method, path, descriptor, description, and original cause when available.

6 exports Added in v4.0.0 Source

Constructors

badArgument

Added in v4.0.0 Source

Creates a PlatformError whose reason is a BadArgument.

When to use

Use to report a platform API rejecting caller input before performing the underlying operation.

Signature

declare function badArgument(options: {
  readonly cause?: unknown;
  readonly description?: string;
  readonly method: string;
  readonly module: string;
}): PlatformError

systemError

Added in v4.0.0 Source

Creates a PlatformError whose reason is a SystemError.

When to use

Use to adapt an operating-system or platform failure into the normalized platform error model.

Signature

declare function systemError(options: {
  readonly _tag: SystemErrorTag;
  readonly cause?: unknown;
  readonly description?: string;
  readonly method: string;
  readonly module: string;
  readonly pathOrDescriptor?: string | number;
  readonly syscall?: string;
}): PlatformError

Errors

BadArgument

Added in v4.0.0 Source

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.

See

  • badArgument for creating a wrapped PlatformError whose reason is BadArgument
  • SystemError for failures reported by the host platform or operating system
  • PlatformError for the wrapper used by most platform APIs

Signature

declare class BadArgument extends YieldableError<this> & {
  readonly _tag: "BadArgument";
} & Readonly<{
  cause?: unknown;
  description?: string;
  method: string;
  module: string;
}> {
  constructor(args: {
    readonly cause?: unknown;
    readonly description?: string;
    readonly method: string;
    readonly module: string;
  });
  message: string;
}

PlatformError

Added in v4.0.0 Source

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.

See

  • BadArgument for invalid inputs rejected before an operation runs
  • SystemError for failures reported by the host platform or operating system
  • badArgument for creating this wrapper from rejected caller input
  • systemError for creating this wrapper from a host or operating-system failure

Signature

declare class PlatformError extends YieldableError<this> & {
  readonly _tag: "PlatformError";
} & Readonly<{
  reason: BadArgument | SystemError;
}> {
  constructor(reason: BadArgument | SystemError);
  readonly "~effect/platform/PlatformError": "~effect/platform/PlatformError";
  message: string;
}

SystemError

Added in v4.0.0 Source

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.

See

  • systemError for creating the usual PlatformError wrapper from this reason data
  • BadArgument for platform API failures caused by rejected caller input before an operation runs
  • SystemErrorTag for the normalized tag values stored in _tag

Signature

declare class SystemError extends Error<{
  _tag: SystemErrorTag;
  cause?: unknown;
  description?: string;
  method: string;
  module: string;
  pathOrDescriptor?: string | number;
  syscall?: string;
}> {
  constructor(args: {
    readonly _tag: SystemErrorTag;
    readonly cause?: unknown;
    readonly description?: string;
    readonly method: string;
    readonly module: string;
    readonly pathOrDescriptor?: string | number;
    readonly syscall?: string;
  });
  message: string;
}

SystemErrorTag type

Added in v4.0.0 Source

Normalized category for failures reported by platform or system operations.

When to use

Use to type or match the normalized _tag on SystemError values reported by platform operations.

Details

The tags group lower-level platform errors into a stable set such as NotFound, PermissionDenied, TimedOut, and Unknown.

See

  • SystemError for the error data that carries this tag on its _tag field
  • systemError for creating a PlatformError from a system failure with one of these tags

Signature

type SystemErrorTag = "AlreadyExists" | "BadResource" | "Busy" | "InvalidData" | "NotFound" | "PermissionDenied" | "TimedOut" | "UnexpectedEof" | "Unknown" | "WouldBlock" | "WriteZero"