Enum Error 

pub enum Error {
    CliNotFound {
        binary: String,
    },
    CwdNotFound {
        path: String,
    },
    Process {
        exit_code: Option<i32>,
        stderr: String,
    },
    Connection {
        reason: String,
    },
    JsonDecode {
        line: u64,
        source: Error,
    },
    MessageParse {
        reason: String,
        data: Option<Value>,
    },
    Encode {
        context: String,
        source: Error,
    },
    Io(Error),
}

All errors surfaced by forge-sdk.

Variants

CliNotFound

The claude binary (or a custom replacement) was not found on PATH.

Wraps the CLI’s CLINotFoundError.

Fields

binary: String

The binary path or name that was attempted.

CwdNotFound

The subprocess’s working directory does not exist.

Separate from Error::CliNotFound because a spawn that cannot enter its cwd fails with the same ENOENT as one that cannot find the binary.

Fields

path: String

The working directory that was attempted.

Process

The subprocess exited with a non-zero status or was terminated by a signal.

Wraps the CLI’s ProcessError.

Fields

exit_code: Option<i32>

Exit status, if the process exited normally.

stderr: String

Captured stderr content (may be truncated).

Connection

Could not establish or maintain the stdio connection to the subprocess.

Wraps the CLI’s CLIConnectionError.

Fields

reason: String

Human-readable explanation.

JsonDecode

A line of stream-json from the subprocess could not be parsed as JSON.

Wraps the CLI’s CLIJSONDecodeError.

Fields

line: u64

1-based line number of the offending line.

source: Error

The underlying serde error.

MessageParse

A stream-json message parsed as JSON but did not match any known message schema.

Wraps the CLI’s MessageParseError (_errors.py:48-55), including the optional data field that carries the offending payload when one is available. the CLI reads this as a dict[str, Any] | None; forge-sdk types it as Option<serde_json::Value> so callers inspecting the failure can recover the decoded JSON without re-parsing the error message.

Fields

reason: String

Human-readable explanation (often includes the offending JSON excerpt).

data: Option<Value>

Decoded CLI payload the failure originated from, when the call site had it in hand. None for failures surfaced before a payload is parsed (e.g. envelope encode failures).

Encode

Forge-sdk failed to JSON-encode a local payload (initialize envelope, control_request body, hook response, session mutation entry, etc.). Distinct from Error::MessageParse, which is for parse failures on data the CLI sent us - Encode is when we couldn’t serialise something locally and the bug is on the SDK or caller side, not the CLI’s. context names what we were trying to encode (e.g. “agents map”, “initialize body”, “user prompt”).

Fields

context: String

What we were trying to encode.

source: Error

The underlying serde error.

Io(Error)

Wrapping std::io::Error for convenience.

Implementations

impl Error

pub fn message_parse(reason: impl Into<String>) -> Self

Construct a Error::MessageParse carrying only a reason string (most call sites). Equivalent to the struct-literal form with data: None.

pub fn encode(context: impl Into<String>, source: Error) -> Self

Construct an Error::Encode for a local JSON encode failure. Use this for serde_json::to_string/to_value failures on data the SDK constructed, NOT for parse failures on incoming CLI bytes.

Trait Implementations

impl Debug for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Error

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for Error

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for Error

fn from(source: Error) -> Self

Converts to this type from the input type.