Enum Error 

#[non_exhaustive]
pub enum Error {
    Interchange(InterchangeError),
    MissingApiKey(String),
    Http(Box<dyn Error + Send + Sync>),
    Provider {
        status: u16,
        body: String,
    },
    Decode(Error),
    InvalidSession(String),
    Sdk(SdkError),
    UnknownTool(String),
    InvalidArguments {
        tool: String,
        message: String,
    },
    Tool {
        tool: String,
        message: String,
    },
    MaxIterations(usize),
    Io(Error),
    ContextLimitExceeded {
        projected_tokens: u64,
        reserve_tokens: u64,
        context_limit: u64,
        model: String,
    },
    SubagentDepthExceeded {
        max_depth: usize,
        attempted_depth: usize,
    },
    SubagentConcurrencyExceeded {
        max_concurrent: usize,
    },
    SubagentBackgroundPolicyMissing,
    SubagentDefinitionNotFound(String),
    SubagentNotFound(String),
    BackgroundJobConcurrencyExceeded {
        max_concurrent: usize,
    },
    BackgroundJobNotFound(String),
    Reduction(ReductionError),
    Other(String),
}

Errors that can arise while configuring or running an crate::Agent.

#[non_exhaustive] so new variants can be added without a breaking release; match with a _ arm.

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.

Interchange(InterchangeError)

A native session interchange operation failed.

MissingApiKey(String)

No API key was provided and none could be found in the environment.

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

The HTTP transport failed. The underlying error is kept as an opaque source rather than exposing the reqwest type, so a transport-library bump is not a breaking change for this crate’s public API.

Provider

The provider returned a non-success status.

Fields

status: u16

HTTP status code.

body: String

Raw response body (truncated upstream if large).

Decode(Error)

A response body could not be parsed.

InvalidSession(String)

A persisted session artifact failed its own framing/schema contract.

Sdk(SdkError)

A versioned SDK/runtime operation failed. Runtime adapters retain this typed value so outer SDK surfaces preserve its stable error name.

UnknownTool(String)

The model asked for a tool that isn’t registered.

Constructed by the agent loop’s run_tool dispatch and fed back to the model as this variant’s Display rendering, so it is load-bearing on the real tool-call path, not just a documented-but-unused variant.

InvalidArguments

A tool’s input arguments were not valid for its schema.

Constructed both by built-in tools’ argument parsing (parse_args) and by the agent loop’s run_tool when the model’s raw argument JSON fails to parse; either way its Display rendering is what the model sees.

Fields

tool: String

The tool that was called.

message: String

What was wrong with the arguments.

Tool

A tool failed while executing.

Fields

tool: String

The tool that failed.

message: String

Failure detail.

MaxIterations(usize)

The agent loop exceeded its configured iteration budget.

Io(Error)

An I/O operation failed.

ContextLimitExceeded

PARITY-18 D4 — a live request would exceed the target model’s context window even after crate::tokens::context_guard’s safety margin and completion reserve are applied. Raised by crate::Agent::run_loop’s per-send guard, which runs before EVERY request this agent issues (not only the first) once crate::Agent::set_context_limit has armed it — so an over-context request is refused at any point in a session, not just at the CLI’s one-shot preflight.

PARITY-18 v3 — projected_tokens is crate::tokens::context_guard’s margin-adjusted estimate of messages+tools ONLY; it does NOT include the completion reserve, so the refusal condition is actually projected_tokens + reserve_tokens > context_limit, not projected_tokens > context_limit — printing the bare comparison (v2’s wording) was arithmetically false as written (e.g. “projected 193,064 > limit 200,000” reads as passing when the refusal is only true once the reserve is added). reserve_tokens is carried on the error so the Display impl states the true inequality.

Fields

projected_tokens: u64

Margin-adjusted projected token count for the request that was about to be sent (messages + tools only; excludes the completion reserve — see reserve_tokens).

reserve_tokens: u64

The completion-token reserve (crate::tokens::CONTEXT_RESPONSE_RESERVE_TOKENS) added to projected_tokens to derive the true refusal condition: projected_tokens + reserve_tokens > context_limit.

context_limit: u64

The target model’s context-window size.

model: String

The model slug this limit was resolved for.

SubagentDepthExceeded

P5-3 (§2 module 9 subagents, §5.3-style resource bound): a spawn_subagent call was refused because it would exceed capabilities.subagents.max_depth — the fail-closed depth cap that keeps a parent-spawning-children-spawning-children chain from growing unbounded. Named so the model (and a test) can tell this apart from every other tool-error shape.

Fields

max_depth: usize

The configured cap.

attempted_depth: usize

The depth the new child would have been spawned at.

SubagentConcurrencyExceeded

P5-3 (§2 module 9, §5.3-style resource bound): a spawn_subagent call was refused because capabilities.subagents.max_concurrent subagents are already in flight ANYWHERE in this spawn tree (the concurrency gauge is shared root-to-leaf) — the fail-closed fork-bomb guard.

Fields

max_concurrent: usize

The configured cap.

SubagentBackgroundPolicyMissing

P5-3 (§2.2 C6): a background: true spawn was refused because no capabilities.subagents.background_prompts auto-policy ("auto_policy" or "parent") is configured — a detached child cannot prompt interactively, so this is enforced fail-closed at spawn time, defensively re-checking what crate::configfile::validate_modules’s C6 resolver rule already requires at config-resolve time (belt-and-suspenders for a Config hand-built via crate::ConfigBuilder that bypassed the resolver).

SubagentDefinitionNotFound(String)

P5-3: spawn_subagent’s agent_type named an agent definition not present in capabilities.subagents.agents.

SubagentNotFound(String)

P5-3: subagent_status (or an internal join) named a subagent id this agent never spawned (or one already reaped).

BackgroundJobConcurrencyExceeded

P5-6 (§2 module 4 tools.background, resource bound): a background_exec call was refused because capabilities.tools_background.max_concurrent background jobs are already running for this agent — fail-closed, mirroring Error::SubagentConcurrencyExceeded’s cap treatment (§2 module 9).

Fields

max_concurrent: usize

The configured cap.

BackgroundJobNotFound(String)

P5-6: background_status/background_kill named a job id this agent never spawned (or one already reaped after finishing).

Reduction(ReductionError)

A reversible reduction invariant or sidecar pointer check failed.

Other(String)

Catch-all for everything else.

Implementations

impl Error

pub fn tool(tool: impl Into<String>, message: impl Into<String>) -> Self

Convenience constructor for a tool failure.

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<Error> for Error

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for Error

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for Error

fn from(e: Error) -> Self

Converts to this type from the input type.

impl From<InterchangeError> for Error

fn from(source: InterchangeError) -> Self

Converts to this type from the input type.

impl From<ReductionError> for Error

fn from(source: ReductionError) -> Self

Converts to this type from the input type.

impl From<SdkError> for Error

fn from(source: SdkError) -> Self

Converts to this type from the input type.