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,
    },
    Cancelled,
    OutputLimitExceeded {
        stream: OutputStream,
        limit_bytes: usize,
    },
    Json {
        message: String,
        source: Error,
    },
    VersionMismatch {
        found: CliVersion,
        minimum: CliVersion,
    },
    UntestedCliVersion {
        found: CliVersion,
        tested_min: CliVersion,
        tested_max: 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,
    },
    #[non_exhaustive]
    MaxTurnsExceeded {
        command: String,
        exit_code: i32,
        max_turns: Option<u32>,
        cost_usd: Option<f64>,
        num_turns: Option<u32>,
        session_id: Option<String>,
    },
    #[non_exhaustive]
    MaxBudgetExceeded {
        command: String,
        exit_code: i32,
        max_usd: Option<f64>,
        cost_usd: Option<f64>,
        num_turns: Option<u32>,
        session_id: Option<String>,
    },
}

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

The full command line that failed.

exit_code: i32

Process exit code.

stdout: String

Captured standard output.

stderr: String

Captured standard error.

working_dir: Option<PathBuf>

Working directory the command ran in, when set.

Io

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

Fields

message: String

Human-readable description of the I/O failure.

source: Error

The underlying I/O error.

working_dir: Option<PathBuf>

Working directory the operation ran in, when set.

Timeout

The command timed out.

Fields

timeout_seconds: u64

The timeout, in seconds, that was exceeded.

Cancelled

The caller explicitly cancelled an in-flight command.

The wrapper does not return this error until it has terminated the owned process group and reaped the direct child.

OutputLimitExceeded

The child wrote more to a captured stream than the configured ceiling allows.

Returned instead of a truncated success, so a caller can tell a complete answer from one that exceeded what it agreed to hold. The wrapper does not return this error until it has terminated the owned process group and reaped the direct child, on the same path as Error::Cancelled and Error::Timeout. Output captured before the ceiling tripped is logged at warn rather than carried here.

Configure the ceiling with ClaudeBuilder::output_limit; it is off by default and this error cannot occur while it is unset.

Fields

stream: OutputStream

Which captured stream exceeded the ceiling.

limit_bytes: usize

The configured ceiling, in bytes, that was exceeded.

Json

JSON parsing failed.

Fields

message: String

Human-readable description of what failed to parse.

source: Error

The underlying serde error.

VersionMismatch

The installed CLI version does not meet the minimum requirement.

Fields

found: CliVersion

The version detected on the system.

minimum: CliVersion

The minimum version required.

UntestedCliVersion

The installed CLI is outside the tested-against range and the caller asked for a hard gate via Claude::ensure_tested_cli_version.

Distinct from Error::VersionMismatch, which is about a caller-declared minimum for one operation. This one carries both bounds because being newer than the tested maximum is also a refusable condition.

Fields

found: CliVersion

The version detected on the system.

tested_min: CliVersion

Lowest CLI version the wrapper supports.

tested_max: CliVersion

Highest CLI version the wrapper has been tested against.

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

Name of the opt-in env var that must be set.

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

Total spend accumulated so far, in USD.

max_usd: f64

The configured ceiling, in USD.

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).

#[non_exhaustive]

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.

This variant is #[non_exhaustive]: match with .. so future field additions are not breaking.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

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.

cost_usd: Option<f64>

Actual spend, from the result event’s total_cost_usd when present.

num_turns: Option<u32>

Turns completed before the cap, from the result event’s num_turns when present.

session_id: Option<String>

Session id from the result event when present; usable to resume the capped run.

#[non_exhaustive]

MaxBudgetExceeded

A --max-budget-usd-capped run hit its spend ceiling. The CLI emits a terminal result event with subtype == "error_max_budget_usd" (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_budget_usd.

The max_usd is claude’s reported cap, not the actual spend. Detection is post-hoc (claude checks the budget after each API call completes), so a run can overspend the cap before tripping.

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.

This is separate from Error::BudgetExceeded, which is the wrapper’s own BudgetTracker ceiling – a different mechanism from claude’s CLI cap.

This variant is #[non_exhaustive]: match with .. so future field additions are not breaking.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

command: String

The full command line that failed.

exit_code: i32

Process exit code (1).

max_usd: Option<f64>

The configured --max-budget-usd cap, parsed from the result event (“Reached maximum budget ($X)”) when present.

cost_usd: Option<f64>

Actual spend, from the result event’s total_cost_usd when present.

num_turns: Option<u32>

Turns completed before the cap, from the result event’s num_turns when present.

session_id: Option<String>

Session id from the result event when present; usable to resume the capped run.

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.