Enum Error 

#[non_exhaustive]
pub enum Error {
    NotFound,
    Auth {
        message: String,
        command: String,
        exit_code: i32,
        working_dir: Option<PathBuf>,
    },
    Config {
        message: String,
        command: String,
        exit_code: i32,
        working_dir: Option<PathBuf>,
    },
    NotTrustedDirectory {
        message: String,
        command: String,
        exit_code: i32,
        working_dir: Option<PathBuf>,
    },
    SessionNotFound {
        message: String,
        command: String,
        exit_code: i32,
        working_dir: Option<PathBuf>,
    },
    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,
    },
    TokenBudgetExceeded {
        total_tokens: u64,
        max_tokens: u64,
    },
    InvalidRolloutBudget {
        message: String,
    },
    ConfigParse {
        path: PathBuf,
        message: String,
    },
    DangerousNotAllowed {
        variable: &'static str,
    },
    Cancelled {
        grace_seconds: u64,
    },
    Json {
        message: String,
        source: Error,
    },
    VersionMismatch {
        found: CliVersion,
        minimum: CliVersion,
    },
    UntestedCliVersion {
        found: CliVersion,
        tested_min: CliVersion,
        tested_max: CliVersion,
    },
}

Errors returned by codex-wrapper operations.

This enum is #[non_exhaustive]: match arms must include a _ catch-all so new variants can be added without a breaking change. This mirrors claude-wrapper’s Error for cross-crate consistency.

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 codex binary was not found in PATH.

Auth

The CLI could not authenticate.

Classified from stderr by Error::from_command_failure; see FailureKind for what that costs. Not retried: the CLI has already retried internally by the time this surfaces, and the credentials will not have changed.

Fields

message: String

The CLI’s stderr, trimmed. Retained whole rather than reduced to the matched line, so nothing is lost to classification.

command: String

exit_code: i32

working_dir: Option<PathBuf>

Config

The CLI rejected the configuration before running.

An unknown key under --strict-config, or a malformed override.

Fields

message: String

The CLI’s stderr, trimmed.

command: String

exit_code: i32

working_dir: Option<PathBuf>

NotTrustedDirectory

The working directory is not a trusted directory or git repo, and --skip-git-repo-check was not set.

Fields

message: String

The CLI’s stderr, trimmed.

command: String

exit_code: i32

working_dir: Option<PathBuf>

SessionNotFound

The session or thread being resumed does not exist.

Fields

message: String

The CLI’s stderr, trimmed.

command: String

exit_code: i32

working_dir: Option<PathBuf>

CommandFailed

A codex 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

TokenBudgetExceeded

A session’s token budget was reached.

Denominated in tokens rather than money because the CLI reports token counts and no cost; see crate::budget.

Fields

total_tokens: u64

Tokens recorded when the ceiling was hit. May exceed max_tokens, since a turn’s usage is only known once it has been spent.

max_tokens: u64

The configured ceiling.

InvalidRolloutBudget

A native rollout-budget configuration was invalid before launch.

Fields

message: String

The failed invariant.

ConfigParse

A file on disk could not be parsed.

Distinct from Error::Config, which is the CLI rejecting a configuration it was given. This one never ran a command, so it carries no exit code and is not a FailureKind.

Fields

path: PathBuf

The file that could not be parsed.

message: String

The parser’s message.

DangerousNotAllowed

A bypass of codex’s safety controls was requested without permission.

See crate::dangerous. Never a command failure: nothing ran.

Fields

variable: &'static str

The environment variable that would have permitted it.

Cancelled

The run was cancelled by the caller.

The process group was asked to stop, given grace_seconds, then killed. Distinct from Error::Timeout, which is the client’s own deadline rather than the caller’s decision.

Fields

grace_seconds: u64

How long the group was given to exit before being killed.

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

UntestedCliVersion

The installed CLI is outside the wrapper’s tested-against range.

Only returned by Codex::ensure_tested_cli_version. The default path reports drift as a CliVersionStatus rather than an error.

Fields

found: CliVersion

tested_min: CliVersion

tested_max: CliVersion

Implementations

impl Error

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

Build an error from a failed command, classifying it by stderr.

Every non-zero exit in this crate goes through here, so a caller can branch on the class rather than substring-matching stderr themselves. An unrecognized failure stays Error::CommandFailed with its output intact, so classification never loses information.

Classification is by message, because it has to be: every failure observed on 0.145.0 exits 1. That makes it sensitive to the CLI rewording a message, which is the cost of doing it here instead of in every caller. tests/contract.rs is where a reworded message should be caught.

pub fn failure_kind(&self) -> Option<FailureKind>

The class of this failure, or None if it is not a command failure.

pub fn exit_code(&self) -> Option<i32>

The process exit code, for any variant that came from one.

Classification moved some failures off Error::CommandFailed, so anything reading an exit code should read it here rather than matching that one variant.

pub fn is_deterministic_failure(&self) -> bool

Whether re-running the identical command could plausibly succeed.

False for the classified failures: each is a deterministic rejection, and the CLI has already retried the auth case internally before it surfaces here.

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.