Errors

‹ docs index

One structured type covers every failure mode — spawn, exit, timeout, cancellation, IO — so a caller pattern-matches on a typed variant instead of parsing strings. Since 3.0, Error is a pointer-sized wrapper — a Box<ErrorReason> — that keeps Result<T, Error> small on the pervasive run path; the variants live on the re-exported [ErrorReason] enum, reached through err.reason() (or moved out with err.into_reason()). The read accessors (code(), is_timeout(), diagnostic(), …) and Display/Debug work on Error directly, unchanged. Several variants look alike at a glance but carry different contracts; this guide is the one page that lays them all out side by side: which variant fires from where, how to classify it, and what to do about it.

Upgrading from 2.x: a direct match err { Error::Exit { .. } => … } becomes match err.reason() { ErrorReason::Exit { .. } => … }. See Upgrading.

• Variant reference
• Variants that look alike but aren't
• Classifiers
• Total classification: kind()
• Stable machine identifiers
• Matching under #[non_exhaustive]
• Errors and retries
• Errors and supervision

Variant reference

Variants that look alike but aren't

• Timeout is captured, Cancelled is always an error. output_string/ output_bytes return Ok with timed_out() == true on a deadline — the caller decides whether that counts as failure. A cancellation, by contrast, reports Err(ErrorReason::Cancelled) on every consuming path, streaming included, because it's a deliberate caller action, not run data. When a run both hits its deadline and gets cancelled, cancellation wins (checked first). See Precedence and interactions.
• Teardown outranks the disposition that requested it. Timeout, inactivity timeout, and Cancelled are reported only after terminal teardown is confirmed (or an already-exited race is confirmed by reap). If a kill/escalation/reap fails, Teardown carries the initiating TeardownCause, original io::Error, and the bounded output prefix instead of claiming a potentially-live tree was handled. It also outranks stdin and pump errors from the same finalization window.
• NotReady is not Timeout. Command::timeout is the run's own contract and kills the tree; a readiness probe's within deadline is a separate clock layered on top of an already-running child, and giving up on it never kills anything. is_timeout() is false for NotReady.
• NotFound vs. Spawn. NotFound is the single representation of "program not found" — bare name or path, any platform, one variant, is_not_found() == true. Spawn is every other OS-level launch failure once the program was located (permissions, a bad cwd, a .cmd/.bat needing cmd.exe) — is_not_found() is false there, so a "not installed?" hint never fires on the wrong condition (e.g. a bad working directory).
• CassetteMiss is not is_not_found. A stale/incomplete cassette and a genuinely missing program are different failures a wrapper needs to tell apart — treating a cassette miss as "optional tool not installed" would silently hide a test-fixture bug.
• Exit vs. Signalled. Both carry captured streams and a Display diagnostic tail, but Exit has a code() and may or may not be a failure (is_success()/ok_codes decide); Signalled has no code at all — code() is None — and is always terminal.
• ResourceLimit means "the cap couldn't be applied", never "the cap fired". It is an admission error: the requested value was nonsensical (Invalid), the platform has no mechanism with whole-tree resource accounting (Unsupported), or a capable mechanism rejected this request (Unenforceable). ProcessGroup::with_options raises it before anything runs and hands back no group. ProcessGroup::update_limits raises it against an already-running group, where it does not mean "nothing changed": the caps are written axis by axis, so a part-way failure can leave a mix of old and new in force — see updating a live group. A cap that was applied and then actually stopped the tree produces no error at all — the child just exits non-zero (or dies by SIGKILL), exactly like a self-inflicted crash. For that question ask the group afterwards: ProcessGroup::limit_evidence() returns a per-axis LimitVerdict — Tripped (authoritative kernel/OS evidence that this cap fired), NotTripped, or Unknown (no evidence available on this mechanism — deliberately not folded into a "no"). Exit codes and signals are never consulted for it, precisely because they cannot tell a cap-driven kill from an ordinary failure. So: ResourceLimit on the error path, limit_evidence on the result path — two different questions, and this error's semantics are unchanged by it. They can land on the same axis on a live group, though: an axis named by a failed update_limits is still read from the counters, because that failure is not a rollback. (Left as a bare code span, not a docs.rs link: LimitVerdict ships in the next release, so a docs.rs URL would 404 until then.)

Classifiers

Total classification: kind()

The classifiers above answer one question each. When you route every failure onto your own shape — a CLI folding each disposition into a distinct process exit code, a cross-language binding raising a matching exception class, a router picking a retry policy — you want one total classification instead of a chain of is_* checks ending in "everything else". err.kind() is that: a compact [ErrorKind] with one bucket per operational disposition, derived from each variant's existing semantics (not invented), and covering every variant — present and future — through an exhaustive match inside the crate.

kind() is a routing answer, deliberately coarser than the variant — it is not a replacement for matching reason() when you need the details (the exit code, the captured streams, the timeout duration, which limit failed). It stays consistent with the point classifiers: is_not_found() ⇔ kind() == NotFound, is_permission_denied() ⇔ PermissionDenied, is_timeout() ⇔ Timeout, is_teardown() ⇔ Teardown, and so on.

ErrorKind mirrors std::io::ErrorKind: it is #[non_exhaustive] and carries an Other bucket, so a downstream match needs a catch-all arm — which is exactly what makes it forward-compatible.

#![allow(unused)]
fn main() {
use processkit::{Error, ErrorKind};

// Fold every failure onto your own exit codes — one arm per kind you care
// about, a catch-all for the rest (kinds are `#[non_exhaustive]`).
fn exit_code(err: &Error) -> i32 {
    match err.kind() {
        ErrorKind::NotFound => 127,
        ErrorKind::PermissionDenied => 126,
        ErrorKind::Timeout => 124,
        ErrorKind::Exit => 1,
        // A future kind (or one behind a feature this build doesn't enable,
        // e.g. ResourceLimit) routes here instead of breaking the build.
        _ => 70,
    }
}

let err = Error::parse("jq", "unexpected token");
assert_eq!(err.kind(), ErrorKind::Other);
assert_eq!(err.kind().name(), "other");
assert_eq!(exit_code(&err), 70);
}

Stable machine identifiers

When you publish a machine-readable contract over this crate's types — a CLI's JSONL schema, a cross-language binding, a structured log field — you need one canonical string per enum variant, not a table you hand-maintain (and that silently mislabels a new variant as "unknown"). The reporting and configuration enums carry that table for you:

The language-neutral, canonical dictionary is spec/identifiers.json. The table below explains the Rust API that produces it; both shapes describe the same contract and must change together.

The identifiers are a compatibility surface, held stable like the rest of the public API: a new variant gets a new identifier, and an existing identifier is never renamed without a major release. They are diagnostic names — a stable vocabulary, not a frozen record schema — and the opt-in report-serde feature puts that very vocabulary on the wire rather than minting a second one: it implements serde::Serialize for the crate's report types, and every enum in them serializes as its name() ({"kind": "exited", "code": 0, "signal_number": null}, never serde's derived {"Exited": 0}), so a consumer that adopted the dictionary and a consumer that serializes a report read the same strings. The single exception is the one the table above already records: Signal::Other has no curated identifier, so a Signal travels as its identifier string when curated and as a bare i32 when not — confined to the signal key, while the raw exit-signal number an Outcome carries is the separate key signal_number. That feature is Serialize-only (these values are reported, never supplied back — see the report-only enums listed below), it never puts captured output, argv or environment values on the wire, and it promises the spelling of what it emits, not a frozen field set: every report type is #[non_exhaustive], keeps its fields private, or both — grown, not frozen — so a minor release may add a key, never rename one, and a consumer must ignore unknown keys. See the crate-root report-serde section for the full rules. Mechanism and ParentDeathCleanup use the spellings downstream tools already publish (job_object/cgroup_v2/process_group, whole_tree/direct_child_only/none), so adopting them needs no migration; the FreeBSD reaper mechanism adds process_reaper in the same shape. SoftStopScope (the group-axis soft-stop reach, process-control) reuses the same whole_tree and none spellings for its shared cases, adding opt_in_members for the Windows partial-reach case. LimitVerdict (limits) is the one entry that is not an error classification at all: it is the post-run answer to "did this cap fire?" (tripped / not_tripped / unknown), while LimitKind / LimitReason describe the admission-time ResourceLimit failure — two different questions, never two spellings of one answer (see Variants that look alike but aren't), and both carry the same stability promise.

#![allow(unused)]
fn main() {
use processkit::{Mechanism, Priority};

// Forward — a stable identifier for machine-readable output:
assert_eq!(Mechanism::CgroupV2.name(), "cgroup_v2");
assert_eq!(Priority::BelowNormal.name(), "below_normal");

// Inverse (a config value, a CLI flag, a call from another language) — an
// honest `None` on an unrecognized name, never a silent default:
assert_eq!(Priority::from_name("below_normal"), Some(Priority::BelowNormal));
assert_eq!(Priority::from_name("turbo"), None);
}

The enums the table above lists as from_name exceptions report a name() but take no inverse, because they are classifications, events or fates the crate reports and never accepts back. Outcome::name() reports the disposition only (exited / signalled / timed_out) — the name alone can't carry the exit code or signal number (read those from code() / signal()), and an Outcome is always reported, never supplied. ErrorKind is the same: a total failure classification the crate hands you via Error::kind(), never one you supply back in. Read the fuller payload from the [ErrorReason] variant when a name isn't enough. ProcessEvent and SupervisionEvent similarly identify lifecycle event kinds; their payloads carry the process output, outcome, timing, or supervision detail. SoftSignal (process-control) names which fate a graceful stop's best-effort soft-signal tier met — sent / unsupported / failed — an observation made after a teardown, never a request; the Signal it concerns travels separately (ShutdownReport::attempted_signal). Signal::name() returns Option because the Other(i32) escape hatch has no curated name (it still has a from_name).

Matching under #[non_exhaustive]

Error — and several of its struct-like variants — are #[non_exhaustive]: a future release can add a variant or field without that being a breaking change, but it also means every downstream match must carry a catch-all arm.

use processkit::{Command, ErrorReason};

#[tokio::main]
async fn main() -> processkit::Result<()> {
    let err = Command::new("maybe-missing-tool").run().await.unwrap_err();

    match err.reason() {
        ErrorReason::NotFound { .. } => eprintln!("is it installed?"),
        ErrorReason::Timeout { .. } => eprintln!("hit its deadline"),
        ErrorReason::Cancelled { .. } => { /* caller-initiated, nothing to log */ }
        ErrorReason::Teardown { cause, operation, .. } => {
            eprintln!("{cause:?} teardown failed during {operation}")
        }
        ErrorReason::Exit { code, .. } => eprintln!("exited with {code}"),
        // #[non_exhaustive]: a future variant (or a today's variant behind a
        // feature this build doesn't enable, e.g. ResourceLimit) falls here.
        other => eprintln!("run failed: {other}"),
    }
    Ok(())
}

Prefer the classifiers above (is_not_found(), is_timeout(), …) over destructuring when all you need is a yes/no answer — they read the variant without you having to keep the catch-all arm in sync as fields are added.

Errors and retries

Command::retry(max_attempts, backoff, classifier) replays a failed run while your classifier accepts the typed error — the classifier is exactly this guide's variant table, read by the caller:

use processkit::{Command, Error};
use std::time::Duration;

#[tokio::main]
async fn main() -> processkit::Result<()> {
    let out = Command::new("curl")
        .args(["-fsS", "https://example.com/api"])
        .timeout(Duration::from_secs(10))
        .retry(3, Duration::from_millis(250), |e: &Error| {
            // Transient: our own deadline, or a spawn/IO condition a bare retry clears.
            e.is_timeout() || e.is_transient()
        })
        .run()
        .await?;
    Ok(())
}

ErrorReason::Cancelled and ErrorReason::Teardown are never retried, whatever the classifier says. A cancelled token stays cancelled; an unconfirmed teardown may have left the failed attempt live, so launching another copy would compound it. See Retries for the full ground rules (stdin re-use, which verbs retry at all).

Errors and supervision

A Supervisor restarts a crashing service rather than replaying one operation, but it faces the same "is this permanent?" question — its give_up_when(classifier) gate is the same classifiers applied to a GiveUpAttempt:

use processkit::{Command, GiveUpAttempt, Supervisor};

#[tokio::main]
async fn main() -> processkit::Result<()> {
    let outcome = Supervisor::new(Command::new("maybe-typo'd-binary"))
        .give_up_when(|attempt| match attempt {
            // The child never started at all — e.g. is_not_found() for ENOENT.
            GiveUpAttempt::Failed(err) => err.is_not_found(),
            // A completed run your own domain knows is a permanent crash.
            GiveUpAttempt::Crashed(res) => res.code() == Some(78),
            _ => false,
        })
        .run()
        .await?;
    println!("stopped: {:?}", outcome.stopped);
    Ok(())
}

GiveUpAttempt::Failed(&Error) is the spawn/IO path (no ProcessResult was ever produced); GiveUpAttempt::Crashed(&ProcessResult<String>) is a completed-but-failing run. A recognized-permanent failure reports StopReason::GaveUp instead of restarting forever. ErrorReason::Cancelled is terminal here too — supervision returns Err(Cancelled) instead of restarting into a still-cancelled token, give_up_when or not.

ErrorReason::ResourceLimit and ErrorReason::Unsupported specifically are how a sandboxing request fails loud instead of silently doing less than asked — see Running untrusted children for the hardening checklist that relies on exactly that honesty.

Next: Running commands · Timeouts, retries & cancellation · Supervision · Running untrusted children