Enum Error 

#[non_exhaustive]
pub enum Error {
    Spawn {
        program: String,
        source: Error,
    },
    Exit {
        program: String,
        code: i32,
        stdout: String,
        stderr: String,
    },
    Timeout {
        program: String,
        timeout: Duration,
    },
    NotReady {
        program: String,
        timeout: Duration,
    },
    Parse {
        program: String,
        message: String,
    },
    Unsupported {
        operation: String,
    },
    Cancelled {
        program: String,
    },
    Io(Error),
}

Errors produced when launching or running a child process.

Spawn failures, a non-zero exit (Exit), timeouts, and IO errors fold into one structured enum, so callers can pattern-match on the failure mode instead of parsing strings.

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

The child process could not be started (binary not found, permission denied, …).

Fields

program: String

The program we tried to launch.

source: Error

The underlying OS error.

Exit

The process ran to completion but exited with a non-zero status.

Produced by the ensure_success helpers; the raw exit code is otherwise reported without erroring (a non-zero exit is not inherently a failure).

Both captured streams are carried (each truncated to 4 KiB): git/jj write decisive diagnostics to stdout on failure (CONFLICT (content): …, nothing to commit, working tree clean), so a caller building a user-facing message wants stdout as a fallback when stderr is empty — see diagnostic.

The one-line Display message appends the last non-empty line of diagnostic, capped at 200 bytes — `git` exited with code 2: fatal: boom — actionable in a log line without dumping multi-KiB streams into it.

Fields

program: String

The program that exited non-zero.

code: i32

The raw process exit code.

stdout: String

Captured standard output (truncated). Not shown in the Display message; kept for callers that need a stdout-borne failure message. For the raw-bytes helper (output_bytes) this is a lossy UTF-8 decode of stdout — the exact bytes remain on the originating ProcessResult.

stderr: String

Captured standard error (truncated). Only its last non-empty line (bounded) appears in the Display message — the full captured text lives here, never poisoning a log line.

Timeout

The process exceeded its configured timeout and was killed.

Fields

program: String

The program that timed out.

timeout: Duration

The deadline that elapsed.

NotReady

A readiness probe (RunningProcess::wait_for_line, wait_for_port, wait_for) did not pass within its deadline — the line never appeared, the port never accepted, the check never returned true, or the child exited before becoming ready.

Distinct from Timeout: a probe deadline is separate from the run’s own Command::timeout, and a failed probe does not kill the child — the caller decides what happens next.

Fields

program: String

The program that did not become ready.

timeout: Duration

The probe deadline that elapsed (or would have — an early child exit fails the probe immediately).

Parse

The process succeeded but its output could not be parsed into the expected shape (e.g. malformed --json). Produced by the fallible-parse helpers on CliClient.

Fields

program: String

The program whose output failed to parse.

message: String

What went wrong.

Unsupported

An operation is not supported by the active containment mechanism on this platform.

Raised by ProcessGroup::signal for any signal other than Signal::Kill on Windows (Job Objects have no POSIX signals), and by signal/suspend/resume on the no-containment target, which has no process tree to act on.

Fields

operation: String

A short description of the operation, e.g. "signal(Hup)" or "suspend".

Cancelled

Available on crate feature cancellation only.

The run was cancelled via its CancellationToken (Command::cancel_on) and its process tree was killed.

Asymmetric with Timeout by design: a timeout is captured (ProcessResult::timed_out) on the non-checking paths, whereas a cancellation is always raised on every consuming path. When a run both times out and is cancelled, cancellation wins (it is checked first).

Fields

program: String

The program that was cancelled.

Io(Error)

An IO error occurred while driving the process (reading a pipe, writing stdin, waiting for exit).

Implementations

impl Error

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

The best human-facing message for a failed run, trimmed of surrounding whitespace: captured standard error if it carries text, otherwise the captured standard output (where git puts CONFLICT … and git commit puts nothing to commit). Returns None when there is no captured output to show — a silent Exit (both streams blank) or any non-Exit variant (Spawn, Timeout, Parse, Io) — so a caller can fall back to the Display message. For the raw, untrimmed stream match on Exit’s fields directly.

Trait Implementations

impl Debug for Error

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

Formats the value using the given formatter.

impl Display for Error

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

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

Converts to this type from the input type.