Enum KopiaError 

pub enum KopiaError {
    Spawn {
        binary: String,
        source: Error,
    },
    NonZeroExit {
        args: String,
        code: Option<i32>,
        class: KopiaErrorClass,
        stderr_tail: String,
    },
    Json {
        context: String,
        source: Error,
    },
    EmptyOutput {
        context: String,
        stderr_tail: String,
    },
    Timeout {
        args: String,
        seconds: u64,
    },
}

Errors produced while invoking kopia or parsing its --json output.

Each variant’s Display is actionable — it names the operation, the failure, and (for non-zero exits) the error class plus the stderr tail — so it can be dropped straight into a status.failure block (ADR §4.10):

use kopiur_kopia::{KopiaError, KopiaErrorClass};

let err = KopiaError::NonZeroExit {
    args: "snapshot create".into(),
    code: Some(1),
    class: KopiaErrorClass::Locked,
    stderr_tail: "repository is locked by another process".into(),
};
assert_eq!(
    err.to_string(),
    "kopia `snapshot create` failed (exit code 1, class Locked): \
     repository is locked by another process",
);
// The class drives the retry decision; the stderr tail is recoverable.
assert_eq!(err.class(), KopiaErrorClass::Locked);
assert!(err.class().is_retryable());
assert_eq!(err.stderr_tail(), Some("repository is locked by another process"));

// A timeout names the args and elapsed seconds, and maps to a retryable class.
let to = KopiaError::Timeout { args: "maintenance run --full".into(), seconds: 3600 };
assert_eq!(to.to_string(), "kopia `maintenance run --full` timed out after 3600s");
assert_eq!(to.class(), KopiaErrorClass::RepositoryUnavailable);

Variants

Spawn

The kopia binary could not be spawned at all (missing binary, not executable, fork failure). Carries the OS error.

Fields

binary: String

Path we attempted to execute.

source: Error

Underlying I/O error.

NonZeroExit

kopia ran but exited with a non-zero status. Carries everything needed to build a status.failure block.

Display renders a clean exit code (no Some(1) Debug leak) and a humanized stderr extract (progress noise dropped, volatile temp-path fragments stripped) — this is what reaches Warning Events, status.failure.message, and logs. The full raw tail is preserved in the stderr_tail field (surfaced via status.failure.stderrTail) for debugging; read it with stderr_tail.

Fields

args: String

The subcommand + args that were run (for diagnostics; secrets are passed via env, never argv).

code: Option<i32>

Process exit code, if one was reported (None if killed by signal).

class: KopiaErrorClass

Best-effort error classification from stderr.

stderr_tail: String

The last STDERR_TAIL_LINES lines of stderr, joined by newlines.

Json

kopia exited 0 (or produced output) but the JSON could not be parsed into the expected type — usually a kopia version skew.

Fields

context: String

What we were trying to parse (e.g. “snapshot create result”).

source: Error

The serde error.

EmptyOutput

We expected a JSON object/array on stdout but found none (kopia printed only progress / nothing) even though it exited 0.

stderr_tail is what makes this diagnosable. Without it the variant carried neither a reason nor an exit code, so a kopia that exited cleanly and explained itself on stderr was indistinguishable from a kopia that said nothing at all — the whole of #351.

Fields

context: String

What we were trying to parse.

stderr_tail: String

The trailing stderr lines, which is where kopia explains a silent success. Empty when kopia really did say nothing.

Timeout

The operation exceeded its configured timeout and was killed.

Fields

args: String

The subcommand + args that were run.

seconds: u64

The timeout that elapsed, in seconds.

Implementations

impl KopiaError

pub fn class(&self) -> KopiaErrorClass

The error class for this error, for retry decisions and metrics. Spawn, JSON-parse, empty-output, and timeout errors map to a fixed class; non-zero exits carry their own classification.

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

The trailing stderr lines, if this error captured any.

Trait Implementations

impl Debug for KopiaError

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

Formats the value using the given formatter.

impl Display for KopiaError

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

Formats the value using the given formatter.

impl Error for KopiaError

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.