Enum Error 

#[non_exhaustive]
pub enum Error {
    Llm(LlmError),
    Tool(ToolError),
    Memory(MemoryError),
    Bus(BusError),
    MaxStepsExceeded {
        steps: u32,
    },
    Cancelled,
    Config(ConfigError),
    BadResponse(String),
    Refused {
        reason: String,
    },
    Handoff {
        agent: String,
        reason: String,
    },
    AppBuildError {
        missing: &'static str,
    },
    ModelSunset {
        model: String,
        since: String,
    },
    Downstream(Box<dyn Error + Send + Sync>),
    Suspended {
        checkpoint: Box<RunCheckpoint>,
        reason: String,
    },
    ResumeReplayBlocked {
        run_id: RunId,
        tools: Vec<String>,
    },
    Other {
        message: String,
        source: Option<Box<dyn Error + Send + Sync + 'static>>,
    },
}

Top-level error returned by klieo-core runtime calls.

Marked #[non_exhaustive] so additional variants can be introduced without a major-version bump on impl crates that match on the enum.

use klieo_core::error::{Error, LlmError};
let e: Error = LlmError::Timeout.into();
assert!(matches!(e, Error::Llm(_)));

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.

Llm(LlmError)

Underlying LLM provider failure.

Tool(ToolError)

Tool invocation failure.

Memory(MemoryError)

Memory persistence failure.

Bus(BusError)

Inter-agent bus failure.

MaxStepsExceeded

Runtime ran the maximum allowed number of LLM/tool steps.

Fields

steps: u32

Step count that was exceeded.

Cancelled

Cooperatively cancelled.

Config(ConfigError)

Configuration validation failure.

BadResponse(String)

LLM reply could not be parsed into the requested typed shape.

Surfaced from the structured-output parser when the raw text content fails JSON deserialization. Always permanent — retrying the same reply will fail identically.

Refused

Caller-installed guardrail refused the LLM call.

Fields

reason: String

Human-readable reason supplied by the guardrail.

Handoff

Caller-installed guardrail requested a handoff to another agent.

Fields

agent: String

Name of the agent the guardrail requested.

reason: String

Human-readable reason for the handoff.

AppBuildError

App builder rejected a build() call because a required port was not configured. missing names the port ("llm", "memory", "bus", "tools") so the caller can point at the specific setter to call.

Fields

missing: &'static str

Stable identifier for the missing port.

ModelSunset

A configured model is past its sunset date in the active model registry.

Fields

model: String

Display form of the offending pin (provider/id@version).

since: String

Sunset date (registry-reported), as a string.

Downstream(Box<dyn Error + Send + Sync>)

A downstream or domain error that doesn’t fit another variant.

Use this to wrap errors from non-klieo code:

use klieo_core::error::Error;
let my_err = std::io::Error::other("db gone");
let e = Error::Downstream(Box::new(my_err));
assert!(std::error::Error::source(&e).is_some());

Suspended

Run suspended at a step awaiting human approval (ADR-045). Carries the checkpoint needed to resume via runtime::resume_from_checkpoint.

Fields

checkpoint: Box<RunCheckpoint>

Serializable continuation state; boxed to keep Error small.

reason: String

Human-readable reason the run paused (from the ReviewPolicy).

ResumeReplayBlocked

A retried resume refused to re-dispatch a non-idempotent tool call (ADR-045 fail-closed). A cross-process resume that has already been attempted cannot prove the pending call did not fire before the crash, so the framework will not risk a duplicate side effect (e.g. a double payout). The checkpoint is left intact for operator reconciliation.

Fields

run_id: RunId

Key under which the un-resumed checkpoint stays for reconciliation.

tools: Vec<String>

Pending tools that could not be proven un-fired, hence the refusal.

Other

Generic wrap for errors produced by downstream consumers that don’t fit any of the typed variants above (agent-impl errors from klieo-spec::QualityLoop, klieo-flows::FlowError, custom domain errors).

Carries the original error as #[source] so e.source() traversal preserves the cause chain. Prefer the typed variants (Llm, Tool, Memory, Bus, Config) when the error class is known.

Fields

message: String

Human-readable context describing where the wrap happened.

source: Option<Box<dyn Error + Send + Sync + 'static>>

Underlying error preserved for std::error::Error::source().

Implementations

impl Error

pub fn wrap<E>(message: impl Into<String>, source: E) -> Self

where E: Error + Send + Sync + 'static,

One-line constructor for Error::Other that boxes the source into the #[source] chain.

use klieo_core::error::Error;
let io = std::io::Error::other("disk gone");
let e = Error::wrap("ledger write failed", io);
assert_eq!(e.to_string(), "ledger write failed");
assert!(std::error::Error::source(&e).is_some());

pub fn retryable(&self) -> bool

Whether the operation is safe to retry without changing inputs.

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, __formatter: &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.

impl From<BusError> for Error

fn from(source: BusError) -> Self

Converts to this type from the input type.

impl From<ConfigError> for Error

fn from(source: ConfigError) -> Self

Converts to this type from the input type.

impl From<LlmError> for Error

fn from(source: LlmError) -> Self

Converts to this type from the input type.

impl From<MemoryError> for Error

fn from(source: MemoryError) -> Self

Converts to this type from the input type.

impl From<ToolError> for Error

fn from(source: ToolError) -> Self

Converts to this type from the input type.