#[non_exhaustive]pub enum ErrorKind {
NotFound,
Spawn,
PermissionDenied,
Unsupported,
Timeout,
Cancelled,
Predicate,
Exit,
Signalled,
Other,
}Expand description
The kind of an Error — a total, compact classification of the failure
into one bucket per operational disposition, reached through
Error::kind / ErrorReason::kind.
Where ErrorReason is the structured failure mode (every field of every
variant), ErrorKind is the routing classification a consumer needs when it
maps failures onto its 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. It is total: every
ErrorReason variant — present and future — maps to exactly one kind, and
the mapping is an exhaustive match inside the crate (no catch-all), so a new
ErrorReason variant cannot ship without a deliberate kind decision.
It is deliberately coarser than ErrorReason and is not a
replacement for matching the reason when you need the details: read
Error::reason for the exit code, the captured streams, the timeout
duration, the PATH searched, and so on. kind() answers “which category of
failure is this?”; reason() answers “what exactly happened?”.
The shape mirrors std::io::Error / std::io::ErrorKind: a rich error
carrying an open-ended set of coarse kinds (hence Other
and #[non_exhaustive]). A downstream match on ErrorKind must therefore
carry a catch-all arm — prefer that to enumerating every kind, so a future
kind routes somewhere sane instead of breaking your build.
Variants (Non-exhaustive)§
This enum is marked as non-exhaustive
NotFound
The program could not be located — from ErrorReason::NotFound. The
twin of Error::is_not_found; the “is it installed?” bucket.
Spawn
The program was located but the OS refused to start it, for a reason
other than a permission denial — from a non-PermissionDenied
ErrorReason::Spawn (a bad working directory, a .cmd/.bat needing
cmd.exe, a transient ETXTBSY/lock, …).
PermissionDenied
A permission denial at the spawn/IO layer — the PermissionDenied subset
of ErrorReason::Spawn / ErrorReason::Io. The twin of
Error::is_permission_denied; split out of Spawn
/ Other because an ACL/executable-bit problem is a
distinct operator action (fix permissions) from a generic launch or IO
failure.
Unsupported
An operation is unsupported by the active containment mechanism on this
platform — from ErrorReason::Unsupported (e.g. any Signal but Kill
on Windows Job Objects).
Timeout
The run exceeded its Command::timeout and was
killed — from ErrorReason::Timeout. The twin of Error::is_timeout.
A readiness-probe deadline (ErrorReason::NotReady) is not this — it
never kills the child — and classifies as Other,
matching is_timeout’s scoping.
Cancelled
The run was deliberately cancelled via its
CancellationToken — from
ErrorReason::Cancelled. The twin of Error::is_cancelled; a
caller-initiated stop, never retried.
Predicate
A fallible control predicate returned an error — from
ErrorReason::Predicate. Its own routing bucket, distinct from
Other: the failure originated in the caller’s own
try_* control predicate (a Supervisor twin or
ScriptedRunner::try_when), so
a wrapper routing failures onto its own shape (a language binding raising a
matching exception, say) can tell “the callback raised” apart from a
backend/IO failure without matching the reason variant. The predicate’s
verbatim error is on the reason
(ErrorReason::Predicate::source).
Exit
The process ran to completion but exited non-zero — from
ErrorReason::Exit. The exit code itself is on the reason
(Error::code).
Signalled
The process was killed by a signal (Unix, or a modelled
double/cassette) — from ErrorReason::Signalled. The twin of
Error::is_signalled; the signal number, when known, is on the reason
(Error::signal).
Other
The catch-all IO/other bucket — every remaining ErrorReason variant
that is not one of the categories above:
CassetteMiss,
Parse, NotReady,
OutputTooLarge,
Stdin, and a non-PermissionDenied
Io. Mirrors std::io::ErrorKind::Other: a genuine
but uncategorized backend/IO failure. Read Error::reason to tell them
apart when it matters.
Implementations§
Source§impl ErrorKind
impl ErrorKind
Sourcepub fn name(&self) -> &'static str
pub fn name(&self) -> &'static str
This kind’s stable machine identifier: a short, lowercase
snake_case string ("not_found", "permission_denied", "exit", …)
that is part of the crate’s compatibility surface.
Use it for machine-readable output — a CLI’s JSONL schema, a
cross-language binding, a structured log field — where a consumer needs
one canonical spelling per kind instead of hand-maintaining its own
mapping table. It is a diagnostic name — a stable vocabulary
rather than a frozen record schema — and the exact string the opt-in
report-serde feature serializes an ErrorKind as. It is held stable
either way: a new kind gets a new
identifier, and an existing identifier is never renamed without a
major release.
There is deliberately no from_name inverse: an ErrorKind is a
classification the crate reports, never one supplied back to it (the
same asymmetry as Outcome::name).