Enum AgentError 

#[non_exhaustive]
pub enum AgentError {
    Llm {
        provider: &'static str,
        reason: LlmFailureReason,
        message: String,
    },
    StoreError(String),
    ToolError(String),
    McpError(String),
    SessionNotFound(SessionId),
    TokenBudgetExceeded {
        used: u64,
        limit: u64,
    },
    TimeBudgetExceeded {
        elapsed_secs: u64,
        limit_secs: u64,
    },
    ToolCallBudgetExceeded {
        count: usize,
        limit: usize,
    },
    MaxTokensReached {
        turn: u32,
        partial: String,
    },
    ContentFiltered {
        turn: u32,
    },
    MaxTurnsReached {
        turns: u32,
    },
    Cancelled,
    InvalidStateTransition {
        from: String,
        to: String,
    },
    OperationNotFound(String),
    DepthLimitExceeded {
        depth: u32,
        max: u32,
    },
    ConcurrencyLimitExceeded,
    ConfigError(String),
    InvalidToolAccess {
        tool: String,
    },
    InternalError(String),
    BuildError(String),
    AuthReauthRequired {
        binding_key: String,
        message: String,
    },
    CallbackPending {
        tool_name: String,
        args: Value,
    },
    StructuredOutputValidationFailed {
        attempts: u32,
        reason: String,
        last_output: String,
    },
    InvalidOutputSchema(String),
    HookDenied {
        hook_id: HookId,
        point: HookPoint,
        reason_code: HookReasonCode,
        message: String,
        payload: Option<Value>,
    },
    HookTimeout {
        hook_id: HookId,
        timeout_ms: u64,
    },
    HookExecutionFailed {
        hook_id: HookId,
        reason: String,
    },
    HookConfigInvalid {
        reason: String,
    },
    TerminalFailure {
        outcome: TurnTerminalOutcome,
        cause_kind: TurnTerminalCauseKind,
        message: String,
    },
    NoPendingBoundary,
}

Errors that can occur during agent execution

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

Fields

provider: &'static str

reason: LlmFailureReason

message: String

StoreError(String)

ToolError(String)

McpError(String)

SessionNotFound(SessionId)

TokenBudgetExceeded

Fields

used: u64

limit: u64

TimeBudgetExceeded

Fields

elapsed_secs: u64

limit_secs: u64

ToolCallBudgetExceeded

Fields

count: usize

limit: usize

MaxTokensReached

Fields

turn: u32

partial: String

ContentFiltered

Fields

turn: u32

MaxTurnsReached

Fields

turns: u32

Cancelled

InvalidStateTransition

Fields

from: String

to: String

OperationNotFound(String)

DepthLimitExceeded

Fields

depth: u32

max: u32

ConcurrencyLimitExceeded

ConfigError(String)

InvalidToolAccess

Fields

tool: String

InternalError(String)

BuildError(String)

Agent construction failed (e.g. missing API key, unknown provider).

AuthReauthRequired

MeerkatMachine DSL observed an auth lease in reauth_required state at a CallingLlm boundary; the lease cannot proceed until the user re-authenticates (rkat auth login). This is a machine-owned terminal class (Phase 1.5-rev), distinct from AgentError::InternalError which is for genuinely unexpected failures.

Fields

binding_key: String

message: String

CallbackPending

A tool call must be routed externally (callback pending)

Fields

tool_name: String

args: Value

StructuredOutputValidationFailed

Structured output validation failed after retries

Fields

attempts: u32

reason: String

last_output: String

InvalidOutputSchema(String)

Invalid output schema provided

HookDenied

Fields

hook_id: HookId

point: HookPoint

reason_code: HookReasonCode

message: String

payload: Option<Value>

HookTimeout

Fields

hook_id: HookId

timeout_ms: u64

HookExecutionFailed

Fields

hook_id: HookId

reason: String

HookConfigInvalid

Fields

reason: String

TerminalFailure

Turn execution reached a terminal outcome classified as HardFailure.

Fields

outcome: TurnTerminalOutcome

cause_kind: TurnTerminalCauseKind

message: String

NoPendingBoundary

The session has no pending user/tool-results boundary for run_pending.

Returned when RuntimeExecutionKind::ResumePending is requested but the session’s last message is not User or ToolResults. The caller should treat this as a successful no-op (no turn ran, no output produced).

Implementations

impl AgentError

pub fn llm( provider: &'static str, reason: LlmFailureReason, message: impl Into<String>, ) -> Self

pub fn is_graceful(&self) -> bool

pub fn is_rate_limited(&self) -> bool

pub fn retry_after_hint(&self) -> Option<Duration>

pub fn is_recoverable(&self) -> bool

Trait Implementations

impl Debug for AgentError

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

Formats the value using the given formatter.

impl Display for AgentError

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

Formats the value using the given formatter.

impl Error for AgentError

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<&AgentError> for AgentErrorClass

fn from(error: &AgentError) -> Self

Converts to this type from the input type.

impl From<AgentError> for CompactionError

fn from(source: AgentError) -> Self

Converts to this type from the input type.

impl From<AgentError> for SessionError

fn from(source: AgentError) -> Self

Converts to this type from the input type.