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

claude_code_agent_sdk/
errors.rs
