claude_sdk_rs/
error.rs

1//! Crate-level error surface for `claude-code-rs`.
2
3/// Errors that can occur while building, spawning, or parsing output from the
4/// `claude` CLI subprocess.
5#[derive(Debug, thiserror::Error)]
6pub enum Error {
7    /// The `claude` binary could not be located (via `CLAUDE_BINARY` or `PATH`).
8    #[error("claude binary not found")]
9    BinaryNotFound,
10
11    /// Spawning or communicating with the child process failed.
12    #[error("failed to spawn claude process: {0}")]
13    Spawn(#[from] std::io::Error),
14
15    /// The call exceeded its configured timeout.
16    #[error("claude call timed out")]
17    Timeout,
18
19    /// The CLI's JSON output could not be parsed into the expected shape.
20    #[error("failed to parse claude output: {0}")]
21    Parse(#[from] serde_json::Error),
22
23    /// The `claude` CLI itself failed before producing a response envelope —
24    /// bad arguments, a missing prompt, a crash. Diagnosed by an empty stdout;
25    /// the message is on stderr.
26    ///
27    /// Distinct from [`Error::Api`]: here the CLI never reached the API.
28    #[error("claude CLI failed (exit {status:?}): {stderr}")]
29    Cli {
30        /// Process exit code, if the process was not killed by a signal.
31        status: Option<i32>,
32        /// The CLI's stderr, trimmed.
33        stderr: String,
34    },
35
36    /// The CLI ran and emitted a well-formed envelope reporting a failure
37    /// (`is_error: true`) — e.g. an unroutable model, or an API outage.
38    ///
39    /// Distinct from [`Error::Cli`]: the CLI worked; the API call did not.
40    /// Note the message arrives on *stdout*, inside the JSON's `result` field —
41    /// stderr is empty on this path.
42    #[error("claude API error{}: {message}", .status.map(|s| format!(" (HTTP {s})")).unwrap_or_default())]
43    Api {
44        /// HTTP status from the envelope's `api_error_status`, when reported.
45        status: Option<u16>,
46        /// Human-readable message from the envelope's `result` field.
47        message: String,
48    },
49
50    /// Setting up an isolated `CLAUDE_CONFIG_DIR` (temp dir creation, or a
51    /// credentials/`.claude.json` source that exists but could not be read
52    /// or copied) failed.
53    #[error("failed to set up isolated config dir: {0}")]
54    Isolation(std::io::Error),
55}
56
57/// Crate-wide `Result` alias using [`Error`].
58pub type Result<T> = std::result::Result<T, Error>;
claude_sdk_rs/error.rs

claude_sdk_rs/
error.rs
