Skip to main content

codex_codes/
error.rs

1//! Error types for the codex-codes crate.
2//!
3//! All fallible operations return [`Result<T>`], which uses [`enum@Error`] as the
4//! error type. The variants cover JSON serialization, I/O, protocol-level
5//! issues, and JSON-RPC errors from the app-server.
6
7use serde_json::Value;
8use thiserror::Error;
9
10/// Error type for parsing failures that preserves the raw frame data.
11///
12/// Returned inside [`Error::Deserialization`] when a message from the
13/// app-server fails to deserialize. The structured fields let consumers
14/// render the offending frame in bug reports without grepping logs.
15///
16/// Two failure modes are represented:
17///
18/// 1. **Bare JSON failure** — the line wasn't valid JSON, or the JSON didn't
19///    match the [`JsonRpcMessage`](crate::JsonRpcMessage) envelope. `raw_line`
20///    is the original line from stdout. `raw_json` is populated when the line
21///    parsed as JSON but didn't fit the envelope; `None` when the line wasn't
22///    even JSON. `method` is `None`.
23///
24/// 2. **Typed decode failure** — the envelope parsed fine (so the JSON-RPC
25///    `method` is known), but the typed payload decode
26///    (`Notification::from_envelope` / `ServerRequest::from_envelope`) failed
27///    on the `params`. `method` carries the JSON-RPC method name. `raw_json`
28///    carries the `params` value. `raw_line` is the re-serialized envelope —
29///    wire-equivalent to what came in, suitable for pasting into a bug report.
30#[derive(Debug, Clone)]
31pub struct ParseError {
32    /// Line from stdout (or re-serialized envelope, for typed-decode failures).
33    pub raw_line: String,
34    /// Parsed JSON value when available (the `params` for typed-decode
35    /// failures; the parsed line for envelope-shape failures).
36    pub raw_json: Option<Value>,
37    /// The underlying serde error description.
38    pub error_message: String,
39    /// JSON-RPC `method` name when the failure happened at the typed-decode
40    /// stage. `None` for bare-JSON / envelope-shape failures.
41    pub method: Option<String>,
42}
43
44impl ParseError {
45    /// Build a [`ParseError`] for a bare-JSON or envelope-shape failure.
46    pub fn from_line(line: impl Into<String>, error: serde_json::Error) -> Self {
47        let raw_line = line.into();
48        let raw_json = serde_json::from_str::<Value>(&raw_line).ok();
49        ParseError {
50            raw_line,
51            raw_json,
52            error_message: error.to_string(),
53            method: None,
54        }
55    }
56
57    /// Build a [`ParseError`] for a typed-decode failure on a notification or
58    /// request whose envelope parsed but whose `params` did not match.
59    ///
60    /// `raw_line` is reconstructed by re-serializing the envelope so consumers
61    /// can render the full offending frame even though the original line was
62    /// already consumed by the envelope decode.
63    pub fn from_envelope(
64        method: impl Into<String>,
65        params: Option<Value>,
66        error: serde_json::Error,
67    ) -> Self {
68        let method = method.into();
69        let raw_line = match &params {
70            Some(p) => format!(
71                r#"{{"method":{},"params":{}}}"#,
72                serde_json::to_string(&method).unwrap_or_else(|_| "\"<unserializable>\"".into()),
73                serde_json::to_string(p).unwrap_or_else(|_| "null".into()),
74            ),
75            None => format!(
76                r#"{{"method":{}}}"#,
77                serde_json::to_string(&method).unwrap_or_else(|_| "\"<unserializable>\"".into()),
78            ),
79        };
80        ParseError {
81            raw_line,
82            raw_json: params,
83            error_message: error.to_string(),
84            method: Some(method),
85        }
86    }
87}
88
89impl std::fmt::Display for ParseError {
90    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
91        match &self.method {
92            Some(m) => write!(
93                f,
94                "Failed to decode params for method {:?}: {} (raw: {})",
95                m, self.error_message, self.raw_line
96            ),
97            None => write!(
98                f,
99                "Failed to parse JSON-RPC message: {} (raw: {})",
100                self.error_message, self.raw_line
101            ),
102        }
103    }
104}
105
106impl std::error::Error for ParseError {}
107
108/// All possible errors from codex-codes operations.
109#[derive(Error, Debug)]
110pub enum Error {
111    /// JSON serialization or deserialization failed.
112    ///
113    /// Returned when request parameters can't be serialized or
114    /// response payloads don't match expected types.
115    #[error("JSON error: {0}")]
116    Json(#[from] serde_json::Error),
117
118    /// An I/O error occurred communicating with the app-server process.
119    ///
120    /// Common causes: process not found, pipe broken, permission denied.
121    #[error("IO error: {0}")]
122    Io(#[from] std::io::Error),
123
124    /// A protocol-level error (e.g., missing stdin/stdout pipes).
125    #[error("Protocol error: {0}")]
126    Protocol(String),
127
128    /// The app-server connection was closed unexpectedly.
129    #[error("Connection closed")]
130    ConnectionClosed,
131
132    /// A message from the server could not be deserialized.
133    ///
134    /// Carries a [`ParseError`] with the offending `method` (when known),
135    /// raw frame, and the underlying serde diagnostic. If you encounter this,
136    /// please report it with the `raw_line` — it likely indicates a protocol
137    /// change.
138    #[error("Deserialization error: {0}")]
139    Deserialization(#[from] ParseError),
140
141    /// The app-server process exited with a non-zero status.
142    #[error("Process exited with status {0}: {1}")]
143    ProcessFailed(i32, String),
144
145    /// The server returned a JSON-RPC error response.
146    ///
147    /// Contains the error code and message from the server, plus the
148    /// optional structured `data` payload verbatim. Some errors carry a typed
149    /// payload there; decode the known ones with helpers such as
150    /// [`Error::model_provider_error`]. See the Codex CLI docs for error code
151    /// meanings.
152    #[error("JSON-RPC error ({code}): {message}")]
153    JsonRpc {
154        code: i64,
155        message: String,
156        data: Option<Value>,
157    },
158
159    /// The server closed the connection (EOF on stdout).
160    ///
161    /// Returned by `request()` if the server exits mid-conversation.
162    #[error("Server closed connection")]
163    ServerClosed,
164
165    /// The CLI binary could not be found on PATH.
166    #[error("Binary not found: '{name}' is not on PATH. Is it installed?")]
167    BinaryNotFound { name: String },
168
169    /// An unclassified error.
170    #[error("Unknown error: {0}")]
171    Unknown(String),
172}
173
174impl From<crate::JsonRpcErrorData> for Error {
175    fn from(err: crate::JsonRpcErrorData) -> Self {
176        Error::JsonRpc {
177            code: err.code,
178            message: err.message,
179            data: err.data,
180        }
181    }
182}
183
184impl Error {
185    /// The structured `data` of a [`Error::JsonRpc`] error, if the server sent
186    /// one. `None` for every other variant.
187    pub fn jsonrpc_data(&self) -> Option<&Value> {
188        match self {
189            Error::JsonRpc { data, .. } => data.as_ref(),
190            _ => None,
191        }
192    }
193
194    /// Decode a [`Error::JsonRpc`] error's `data` as a
195    /// [`ModelProviderError`](crate::protocol::ModelProviderError).
196    ///
197    /// The app-server attaches one when a thread's stored model provider
198    /// can't be used, e.g. `thread/resume` of a thread created under a
199    /// provider this machine doesn't configure or policy forbids. `None`
200    /// when there is no `data` or it has a different shape; callers should
201    /// then fall back to `code`/`message`.
202    pub fn model_provider_error(&self) -> Option<crate::protocol::ModelProviderError> {
203        serde_json::from_value(self.jsonrpc_data()?.clone()).ok()
204    }
205}
206
207/// A `Result` type alias using [`enum@Error`].
208pub type Result<T> = std::result::Result<T, Error>;
209
210#[cfg(test)]
211mod tests {
212    use super::*;
213    use serde_json::json;
214
215    fn serde_err(s: &str) -> serde_json::Error {
216        serde_json::from_str::<Value>(s).unwrap_err()
217    }
218
219    #[test]
220    fn parse_error_from_line_valid_json_populates_raw_json() {
221        let line = r#"{"foo":"bar"}"#;
222        // Force a downstream typed-decode failure to produce a serde_json::Error;
223        // we just need *some* error to attach.
224        let err = serde_json::from_str::<i32>(line).unwrap_err();
225
226        let pe = ParseError::from_line(line, err);
227        assert_eq!(pe.raw_line, line);
228        assert_eq!(pe.raw_json, Some(json!({"foo": "bar"})));
229        assert!(pe.method.is_none());
230        assert!(!pe.error_message.is_empty());
231    }
232
233    #[test]
234    fn parse_error_from_line_invalid_json_has_none_raw_json() {
235        let line = "not-json{";
236        let err = serde_err(line);
237
238        let pe = ParseError::from_line(line, err);
239        assert_eq!(pe.raw_line, line);
240        assert!(pe.raw_json.is_none());
241        assert!(pe.method.is_none());
242    }
243
244    #[test]
245    fn parse_error_from_envelope_carries_method_params_and_reconstructs_line() {
246        let params = json!({"callId": null, "kind": "fileChange"});
247        let err = serde_json::from_value::<i32>(params.clone()).unwrap_err();
248
249        let pe =
250            ParseError::from_envelope("item/fileChange/requestApproval", Some(params.clone()), err);
251
252        assert_eq!(
253            pe.method.as_deref(),
254            Some("item/fileChange/requestApproval")
255        );
256        assert_eq!(pe.raw_json, Some(params.clone()));
257
258        // raw_line round-trips to the same shape (re-parse what we built).
259        let v: Value = serde_json::from_str(&pe.raw_line).unwrap();
260        assert_eq!(v["method"], "item/fileChange/requestApproval");
261        assert_eq!(v["params"], params);
262    }
263
264    #[test]
265    fn parse_error_from_envelope_handles_missing_params() {
266        let err = serde_err("not json");
267        let pe = ParseError::from_envelope("turn/completed", None, err);
268        let v: Value = serde_json::from_str(&pe.raw_line).unwrap();
269        assert_eq!(v["method"], "turn/completed");
270        assert!(v.get("params").is_none());
271        assert!(pe.raw_json.is_none());
272    }
273
274    #[test]
275    fn error_deserialization_display_includes_method_and_raw() {
276        let params = json!({"foo": 1});
277        let err = serde_err("not json");
278        let pe = ParseError::from_envelope("item/bogus", Some(params), err);
279        let e: Error = Error::Deserialization(pe);
280        let rendered = format!("{}", e);
281        assert!(rendered.contains("item/bogus"), "got: {}", rendered);
282        assert!(rendered.contains("foo"), "got: {}", rendered);
283    }
284
285    fn jsonrpc(data: Option<Value>) -> Error {
286        crate::JsonRpcErrorData {
287            code: -32600,
288            message: "bad".to_string(),
289            data,
290        }
291        .into()
292    }
293
294    #[test]
295    fn model_provider_error_decodes_policy_conflict() {
296        let err = jsonrpc(Some(json!({
297            "type": "modelProviderPolicyConflict",
298            "modelProvider": "old",
299            "requiredModelProvider": "corp"
300        })));
301        assert_eq!(
302            err.model_provider_error(),
303            Some(
304                crate::protocol::ModelProviderError::ModelProviderPolicyConflict {
305                    model_provider: "old".to_string(),
306                    required_model_provider: "corp".to_string(),
307                }
308            )
309        );
310    }
311
312    #[test]
313    fn model_provider_error_none_for_other_data_and_variants() {
314        let other = json!({"reason": "cloudConfigBundle", "detail": "x"});
315        let err = jsonrpc(Some(other.clone()));
316        assert_eq!(err.jsonrpc_data(), Some(&other));
317        assert!(err.model_provider_error().is_none());
318
319        let bare = jsonrpc(None);
320        assert!(bare.jsonrpc_data().is_none());
321        assert!(bare.model_provider_error().is_none());
322
323        let not_rpc = Error::Protocol("x".to_string());
324        assert!(not_rpc.jsonrpc_data().is_none());
325        assert!(not_rpc.model_provider_error().is_none());
326    }
327}