Enum RunError 

#[non_exhaustive]
pub enum RunError {
    Spawn {
        command: CmdDisplay,
        source: Error,
    },
    NonZeroExit {
        command: CmdDisplay,
        status: ExitStatus,
        stdout: Vec<u8>,
        stderr: String,
        attempts: u32,
    },
    Timeout {
        command: CmdDisplay,
        elapsed: Duration,
        stdout: Vec<u8>,
        stderr: String,
        attempts: u32,
    },
    Cancelled {
        command: CmdDisplay,
        stdout: Vec<u8>,
        stderr: String,
        attempts: u32,
    },
}

Error type for subprocess execution.

Distinguishes between:

• Spawn: infrastructure failure (binary missing, fork failed, etc.)
• NonZeroExit: the command ran and reported failure via exit code
• Timeout: the command was killed after exceeding its timeout
• Cancelled: the caller signaled cancellation via Cmd::cancel

All variants carry a CmdDisplay that formats the command shell-style for logging (with secret redaction if the command was marked .secret()).

NonZeroExit, Timeout, and Cancelled variants carry the last 128 KiB of stdout and stderr (capped by STREAM_SUFFIX_SIZE) — enough context to debug most failures, bounded so a runaway process can’t blow up your error path’s memory.

Attempt count

NonZeroExit, Timeout, and Cancelled carry an attempts field (read via attempts) — the 1-based index of the attempt on which this error occurred. For a Cmd without retry, this is always 1. For a retried command, it tells the caller how many tries happened before the final error (e.g. attempts == 3 on a default policy means the retry budget was exhausted). Spawn doesn’t carry it because Spawn failures by default don’t trigger retries.

Marked #[non_exhaustive] so future variants can be added without breaking callers. Match with a wildcard arm to handle unknown variants defensively.

let cmd = Cmd::new("git").args(&["show", "maybe-missing-ref"]);
let maybe_bytes = match cmd.run() {
    Ok(output) => Some(output.stdout),
    Err(RunError::NonZeroExit { .. }) => None,   // ref not found
    Err(e) => return Err(e.into()),              // real failure bubbles up
};

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.

Spawn

Failed to spawn the child process. The binary may be missing, the working directory may not exist, or the OS may have refused the fork.

Fields

command: CmdDisplay

source: Error

NonZeroExit

The child process ran but exited non-zero. stdout/stderr carry the last STREAM_SUFFIX_SIZE bytes captured before exit (empty for inherited stderr/stdout). attempts is the 1-based retry attempt on which this failure occurred (1 if .retry() was not set).

Fields

command: CmdDisplay

status: ExitStatus

stdout: Vec<u8>

stderr: String

attempts: u32

Timeout

The child process was killed after exceeding the caller’s timeout. elapsed records how long the process ran. stdout/stderr carry any output collected before the kill signal. attempts is the 1-based retry attempt on which the timeout fired.

Fields

command: CmdDisplay

elapsed: Duration

stdout: Vec<u8>

stderr: String

attempts: u32

Cancelled

The caller signaled cancellation via Cmd::cancel. The child was killed (SIGTERM, then SIGKILL after the grace period on Unix; immediate TerminateProcess on Windows). stdout/stderr carry any output captured before the kill. attempts is the 1-based retry attempt that was in flight when cancellation fired; if the flag was already set before the first spawn, attempts == 1 and the captured streams are empty.

Fields

command: CmdDisplay

stdout: Vec<u8>

stderr: String

attempts: u32

Implementations

impl RunError

pub fn command(&self) -> &CmdDisplay

The command that failed, formatted for display (shell-quoted, secret-redacted).

pub fn program(&self) -> &OsStr

The program name. Convenience for self.command().program().

pub fn stderr(&self) -> Option<&str>

The captured stderr suffix, if any. None for spawn failures.

Stderr is stored after lossy UTF-8 decoding — any invalid sequences from the child appear as U+FFFD replacement characters. Callers that truly need raw bytes should inspect the child’s stderr directly via Cmd::spawn.

pub fn stdout(&self) -> Option<&[u8]>

The captured stdout suffix, if any. None for spawn failures.

pub fn exit_status(&self) -> Option<ExitStatus>

The exit status, if the process actually ran to completion. None for spawn failures, timeouts, and cancellations.

pub fn attempts(&self) -> u32

The 1-based retry attempt number on which this error occurred.

Always 1 for Spawn (spawn failures don’t trigger retries by default; this method returns 1 rather than Option<u32> to keep the API ergonomic). For NonZeroExit/Timeout/Cancelled, this is the attempt on which the failure occurred — e.g. 3 on a default RetryPolicy means the retry budget was fully consumed.

pub fn is_non_zero_exit(&self) -> bool

Whether this error represents a non-zero exit (the command ran and reported failure).

pub fn is_spawn_failure(&self) -> bool

Whether this error represents a spawn failure (couldn’t start the process).

pub fn is_timeout(&self) -> bool

Whether this error represents a timeout (process killed after exceeding its time budget).

pub fn is_cancelled(&self) -> bool

Whether this error represents caller-driven cancellation via Cmd::cancel.

Trait Implementations

impl Debug for RunError

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Display for RunError

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Error for RunError

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.