Enum Error 

#[non_exhaustive]
pub enum Error {
    NotFound,
    CommandFailed {
        command: String,
        exit_code: i32,
        stdout: String,
        stderr: String,
        working_dir: Option<PathBuf>,
    },
    Io {
        message: String,
        source: Error,
        working_dir: Option<PathBuf>,
    },
    Timeout {
        timeout_seconds: u64,
    },
    Json {
        message: String,
        source: Error,
    },
    VersionMismatch {
        found: CliVersion,
        minimum: CliVersion,
    },
    DangerousNotAllowed {
        env_var: &'static str,
    },
    BudgetExceeded {
        total_usd: f64,
        max_usd: f64,
    },
    DuplexClosed,
    DuplexTurnInFlight,
    DuplexControlFailed {
        message: String,
    },
    History {
        message: String,
    },
    Artifacts {
        message: String,
    },
    Worktrees {
        message: String,
    },
    Auth {
        kind: AuthErrorKind,
        command: String,
        exit_code: i32,
        message: String,
    },
    MaxTurnsExceeded {
        command: String,
        exit_code: i32,
        max_turns: Option<u32>,
    },
}

Errors returned by claude-wrapper operations.

This enum is #[non_exhaustive]: new variants may be added in future releases without a major version bump, so downstream match expressions must include a wildcard (_ =>) arm. Matching on the specific variants you care about (e.g. Error::Auth, Error::MaxTurnsExceeded) keeps working across upgrades.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

NotFound

The claude binary was not found in PATH.

CommandFailed

A claude command failed with a non-zero exit code.

Fields

command: String

exit_code: i32

stdout: String

stderr: String

working_dir: Option<PathBuf>

Io

An I/O error occurred while spawning or communicating with the process.

Fields

message: String

source: Error

working_dir: Option<PathBuf>

Timeout

The command timed out.

Fields

timeout_seconds: u64

Json

JSON parsing failed.

Fields

message: String

source: Error

VersionMismatch

The installed CLI version does not meet the minimum requirement.

Fields

found: CliVersion

minimum: CliVersion

DangerousNotAllowed

Construction of a dangerous::Client was attempted without the opt-in env-var set. The env-var name is a compile-time constant exported from crate::dangerous::ALLOW_ENV.

Fields

env_var: &'static str

BudgetExceeded

A configured BudgetTracker has hit its max_usd ceiling. Raised before the next call is dispatched, so the CLI is not invoked.

Fields

total_usd: f64

max_usd: f64

DuplexClosed

A DuplexSession operation was attempted after the session task exited (child died, EOF on stdout, or the session was closed). Pending replies are resolved with this error.

DuplexTurnInFlight

DuplexSession::send was called while another turn is already in flight. Wait for the outstanding turn to resolve before issuing another.

DuplexControlFailed

A control request issued from DuplexSession::interrupt (or any other outbound control_request) was answered by the CLI with a subtype: "error" payload.

Fields

message: String

The error message extracted from the CLI’s control_response.

History

A history-module operation (parsing or locating session JSONL under ~/.claude/projects/) failed in a way that doesn’t fit the I/O or JSON variants – e.g. unknown session id, missing user home directory.

Fields

message: String

Human-readable description of what went wrong.

Artifacts

An artifacts-module operation (parsing or locating files under ~/.claude/agents/, ~/.claude/skills/, and friends) failed in a way that doesn’t fit the I/O variant – e.g. unknown agent/skill name, missing user home directory.

Fields

message: String

Human-readable description of what went wrong.

Worktrees

A worktrees-module operation (running or parsing git worktree list --porcelain) failed in a way that doesn’t fit the I/O variant – e.g. git not on PATH, path isn’t a git repo, malformed porcelain output.

Fields

message: String

Human-readable description of what went wrong.

Auth

A claude invocation failed and looked auth-shaped to the classifier. Hosts can match on this variant to trigger a re-auth flow, surface a clean message, or skip retries. kind carries the best-effort subcategory; message is the stderr (or stdout fallback) the classifier matched against.

Raised at exec time when crate::auth::classify_failure returns Some(_) for a CLI failure that would otherwise have been Error::CommandFailed. Cases the classifier missed remain CommandFailed; call Error::auth_kind for opt-in inspection of those.

Fields

kind: AuthErrorKind

Best-effort classification.

command: String

The full command line that failed.

exit_code: i32

Process exit code.

message: String

Human-readable message extracted from stderr (or stdout).

MaxTurnsExceeded

A --max-turns-capped run exhausted its turn budget. The CLI emits a terminal result event with subtype == "error_max_turns" (exit 1, with the result JSON on stdout), which would otherwise fold into Error::CommandFailed.

This is distinct from a genuine failure: the working tree may be fine and the run simply hit the cap mid-task. Orchestrators can match this variant to finish the lifecycle (run remaining gates, commit) rather than treating it as broken or re-parsing the trace for error_max_turns.

Raised by Error::from_command_failure ahead of the auth classifier. Only detected when the result event is present on stdout (the json / stream-json output formats); text-mode failures without it remain Error::CommandFailed.

Fields

command: String

The full command line that failed.

exit_code: i32

Process exit code (1).

max_turns: Option<u32>

The configured --max-turns cap, parsed from the result event (“Reached maximum number of turns (N)”) when present.

Implementations

impl Error

pub fn from_command_failure( command: String, exit_code: i32, stdout: String, stderr: String, working_dir: Option<PathBuf>, ) -> Self

Construct an Error from a CLI failure. Runs the auth-error classifier; if it matches, returns Error::Auth. Otherwise returns Error::CommandFailed unchanged.

This is the canonical entry point for raising failures from exec.rs-shaped sites – replacing direct construction of CommandFailed ensures every consumer benefits from typed auth errors automatically.

pub fn auth_kind(&self) -> Option<AuthErrorKind>

Inspect whether this error is auth-shaped. Returns Some(kind) for Error::Auth (the auto-typed path) and also re-runs crate::auth::classify_failure on Error::CommandFailed for cases the constructor missed. Returns None for everything else (Io, Timeout, etc.).

Most consumers should match on Error::Auth directly – this method is the escape hatch for low-confidence classifier patterns the constructor was too conservative about.

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(e: Error) -> Self

Converts to this type from the input type.