Enum Error 

pub enum Error {
    Session(Outcome),
    Io {
        source: Error,
        context: String,
        path: Option<PathBuf>,
    },
    TomlParse {
        path: PathBuf,
        message: String,
    },
    JsonParse {
        context: String,
        message: String,
    },
    SubprocessSpawn {
        program: String,
        source: Error,
    },
    Cli {
        clap_exit_code: i32,
        message: String,
    },
    CompatPatchOverrideConflict {
        crate_name: String,
        upstream_entry: String,
        expected_resolution: String,
    },
    OverlayMirrorFailed {
        upstream_entry: PathBuf,
        staged_target: PathBuf,
        stage: String,
        source: Option<Error>,
    },
}

Crate-wide error type.

Session(_) is the session-level path. Everything else is an internal failure that bubbles up through ? and is rendered to stderr by main before exiting.

Variants

Session(Outcome)

A session-level outcome. The binary’s exit code is derived from the wrapped Outcome::exit_code(); the diagnostic is printed to stderr verbatim.

Io

Filesystem / I/O failure. The path that was being touched is preserved so error messages name what failed.

Fields

source: Error

The OS error.

context: String

What was being attempted (“read manifest”, “spawn rustc”, …).

path: Option<PathBuf>

Optional path, when one is in scope.

TomlParse

Cargo.toml could not be parsed as TOML. This is distinct from Outcome::ConfigInvalid because the latter assumes TOML parsing succeeded and points to a specific key-level issue.

Fields

path: PathBuf

The path that failed to parse.

message: String

Human-readable parse error.

JsonParse

JSON decode failure (manifest reads, cargo --message-format=json stream, etc.). Treated as internal — the user typically did not produce the JSON.

Fields

context: String

What was being parsed.

message: String

Decoder’s message.

SubprocessSpawn

Subprocess (cargo, rustc) could not be spawned at all (binary not found, permission denied). Distinct from a non-zero exit, which is a normal session outcome.

Fields

program: String

The program name.

source: Error

The OS error.

Cli

CLI argument parsing failed. Carries clap’s exit code so the binary can exit transparently.

Fields

clap_exit_code: i32

clap’s recommended exit code (typically 2).

message: String

The error message clap already printed (kept for tests).

CompatPatchOverrideConflict

The upstream Cargo.toml declared a [patch.crates-io.<self>] entry that compat-mode’s Option H self-patch policy cannot safely overwrite — the entry targets a vendored fork (path resolves to a non-root directory), a git source, or both.

Surfaced by the compat overlay materializer’s Rule 4 (REJECT) branch. The §3.3 envelope renders this as an overlay-stage error; the operator sees the structured message verbatim so they can resolve by reshaping their upstream’s [patch.crates-io] table or filing an issue with the manifest shape they need.

See src/compat/overlay.rs::apply_self_patch_policy for the 4-rule decision tree.

Fields

crate_name: String

The crate name (the upstream’s [package].name) keying the rejected [patch.crates-io.<crate_name>] entry.

upstream_entry: String

A Debug rendering of the upstream’s existing entry, so the operator can see exactly what compat-mode refused to overwrite.

expected_resolution: String

Human-readable explanation of what compat-mode would have done (Rule 1 INJECT / Rule 2 REMAP) and why the upstream’s existing entry blocks it.

OverlayMirrorFailed

Staged package-root mirror step failed.

After the overlay manifest is written to <upstream>/target/lihaaf-overlay/Cargo.toml, the materializer creates symlinks (or copies on platforms where symlinks are unavailable) for each top-level entry in the upstream package directory so build scripts can read package-root files via CARGO_MANIFEST_DIR / cwd. This variant surfaces when an individual symlink, copy, or stale-state reconcile step fails during that pass.

See src/compat/overlay.rs::mirror_upstream_into_overlay and issues #40 / #47 for the build-script file-access failure shapes the mirror resolves.

Fields

upstream_entry: PathBuf

The upstream entry path that was being mirrored (e.g. /work/cxx/src for <upstream>/src).

staged_target: PathBuf

The destination path inside the staged overlay (e.g. /work/cxx/target/lihaaf-overlay/src).

stage: String

Human-readable description of which stage failed (symlink creation, copy fallback, stale-state removal, post-condition assertion).

source: Option<Error>

The OS-level I/O error, when one is in scope. None for post-condition assertion failures that report a structural mismatch rather than an io::Error.

Implementations

impl Error

pub fn io( source: Error, context: impl Into<String>, path: Option<PathBuf>, ) -> Self

Convenience: wrap an io::Error with context + optional path.

pub fn overlay_mirror_failed( upstream_entry: PathBuf, staged_target: PathBuf, stage: impl Into<String>, source: Option<Error>, ) -> Self

Convenience constructor for Error::OverlayMirrorFailed.

stage is a short human-readable label naming which step failed (e.g. "symlink", "copy-fallback", "stale-removal", "post-condition-assertion"); see src/compat/overlay.rs::mirror_upstream_into_overlay for the enumerated stages.

impl Error

pub fn exit_code(&self) -> ExitCode

Exit code reported by the binary when this error is propagated. CLI errors carry clap’s recommended code (typically 2). Other internal errors map to CONFIG_INVALID (64) — they happened before fixtures could run and the user has no fixture verdicts to interpret.

Trait Implementations

impl Debug for Error

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

Formats the value using the given formatter.

impl Display for Error

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

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.