claude_code_agent_sdk/
errors.rs

1//! Error types for the Claude Agent SDK
2
3use std::path::PathBuf;
4use thiserror::Error;
5
6/// Main error type for the Claude Agent SDK
7#[derive(Debug, Error)]
8pub enum ClaudeError {
9    /// CLI connection error
10    #[error("CLI connection error: {0}")]
11    Connection(#[from] ConnectionError),
12
13    /// Process error
14    #[error("Process error: {0}")]
15    Process(#[from] ProcessError),
16
17    /// JSON decode error
18    #[error("JSON decode error: {0}")]
19    JsonDecode(#[from] JsonDecodeError),
20
21    /// Message parse error
22    #[error("Message parse error: {0}")]
23    MessageParse(#[from] MessageParseError),
24
25    /// Transport error
26    #[error("Transport error: {0}")]
27    Transport(String),
28
29    /// Control protocol error
30    #[error("Control protocol error: {0}")]
31    ControlProtocol(String),
32
33    /// Timeout error
34    #[error("Timeout: {0}")]
35    Timeout(String),
36
37    /// Invalid configuration
38    #[error("Invalid configuration: {0}")]
39    InvalidConfig(String),
40
41    /// CLI not found error
42    #[error("CLI not found: {0}")]
43    CliNotFound(#[from] CliNotFoundError),
44
45    /// Image validation error
46    #[error("Image validation error: {0}")]
47    ImageValidation(#[from] ImageValidationError),
48
49    /// MCP error with JSONRPC error code
50    #[error("MCP error: {0}")]
51    Mcp(#[from] McpError),
52
53    /// IO error
54    #[error("IO error: {0}")]
55    Io(#[from] std::io::Error),
56
57    /// Other errors
58    #[error(transparent)]
59    Other(#[from] anyhow::Error),
60}
61
62/// Error when Claude Code CLI cannot be found
63#[derive(Debug, Error)]
64#[error("CLI not found: {message}")]
65pub struct CliNotFoundError {
66    /// Error message
67    pub message: String,
68    /// Path that was checked
69    pub cli_path: Option<PathBuf>,
70}
71
72impl CliNotFoundError {
73    /// Create a new CLI not found error
74    pub fn new(message: impl Into<String>, cli_path: Option<PathBuf>) -> Self {
75        Self {
76            message: message.into(),
77            cli_path,
78        }
79    }
80}
81
82/// Error when connecting to Claude Code CLI
83#[derive(Debug, Error)]
84#[error("Connection error: {message}")]
85pub struct ConnectionError {
86    /// Error message
87    pub message: String,
88}
89
90impl ConnectionError {
91    /// Create a new connection error
92    pub fn new(message: impl Into<String>) -> Self {
93        Self {
94            message: message.into(),
95        }
96    }
97}
98
99/// Error when the CLI process fails
100#[derive(Debug, Error)]
101#[error("Process error (exit code {exit_code:?}): {message}")]
102pub struct ProcessError {
103    /// Error message
104    pub message: String,
105    /// Process exit code
106    pub exit_code: Option<i32>,
107    /// stderr output
108    pub stderr: Option<String>,
109}
110
111impl ProcessError {
112    /// Create a new process error
113    pub fn new(message: impl Into<String>, exit_code: Option<i32>, stderr: Option<String>) -> Self {
114        Self {
115            message: message.into(),
116            exit_code,
117            stderr,
118        }
119    }
120}
121
122/// Error when JSON decoding fails
123#[derive(Debug, Error)]
124#[error("JSON decode error: {message}")]
125pub struct JsonDecodeError {
126    /// Error message
127    pub message: String,
128    /// The line that failed to decode
129    pub line: String,
130}
131
132impl JsonDecodeError {
133    /// Create a new JSON decode error
134    pub fn new(message: impl Into<String>, line: impl Into<String>) -> Self {
135        Self {
136            message: message.into(),
137            line: line.into(),
138        }
139    }
140}
141
142/// Error when message parsing fails
143#[derive(Debug, Error)]
144#[error("Message parse error: {message}")]
145pub struct MessageParseError {
146    /// Error message
147    pub message: String,
148    /// The data that failed to parse
149    pub data: Option<serde_json::Value>,
150}
151
152impl MessageParseError {
153    /// Create a new message parse error
154    pub fn new(message: impl Into<String>, data: Option<serde_json::Value>) -> Self {
155        Self {
156            message: message.into(),
157            data,
158        }
159    }
160}
161
162/// Image validation error
163#[derive(Debug, Error)]
164#[error("Image validation error: {message}")]
165pub struct ImageValidationError {
166    /// Error message
167    pub message: String,
168}
169
170impl ImageValidationError {
171    /// Create a new image validation error
172    pub fn new(message: impl Into<String>) -> Self {
173        Self {
174            message: message.into(),
175        }
176    }
177}
178
179/// MCP (Model Context Protocol) error with JSONRPC error code
180#[derive(Debug, Error)]
181#[error("MCP error ({code}): {message}")]
182pub struct McpError {
183    /// JSONRPC error code
184    pub code: i32,
185    /// Error message
186    pub message: String,
187}
188
189impl McpError {
190    /// Create a new MCP error
191    pub fn new(code: i32, message: impl Into<String>) -> Self {
192        Self {
193            code,
194            message: message.into(),
195        }
196    }
197
198    /// Method not found error (-32601)
199    pub fn method_not_found(method: &str) -> Self {
200        Self::new(-32601, format!("Method not found: {}", method))
201    }
202
203    /// Internal error (-32603)
204    pub fn internal_error(message: impl Into<String>) -> Self {
205        Self::new(-32603, message)
206    }
207
208    /// Invalid params error (-32602)
209    pub fn invalid_params(message: impl Into<String>) -> Self {
210        Self::new(-32602, message)
211    }
212}
213
214/// Result type for the Claude Agent SDK
215pub type Result<T> = std::result::Result<T, ClaudeError>;
claude_code_agent_sdk/errors.rs

claude_code_agent_sdk/
errors.rs
