PlatformError unstable

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.

7 exports Since v4.0.0 Source

Constructors

badArgument

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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

unstable

Since v4.0.0

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/PlatformError": "~effect/PlatformError";
  message: string;
}

SystemError

unstable

Since v4.0.0

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 unstable

Since v4.0.0

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"

Guards

isPlatformError

unstable

Since v4.0.0

Returns true if a value is a PlatformError.

When to use

Use to narrow a caught defect, or an error channel typed more loosely than the platform APIs, to PlatformError.

Signature

declare function isPlatformError(u: unknown): u is PlatformError

Example Checking a caught value

import { PlatformError } from "effect"

const error = PlatformError.badArgument({
  module: "FileSystem",
  method: "readFile"
})

PlatformError.isPlatformError(error) // => true
PlatformError.isPlatformError(new Error("boom")) // => false