Enum DispatchError 

#[non_exhaustive]
pub enum DispatchError {
    ServerNotFound(String),
    ToolNotFound {
        server: String,
        tool: String,
    },
    Timeout {
        server: String,
        timeout_ms: u64,
    },
    CircuitOpen(String),
    GroupPolicyDenied {
        reason: String,
    },
    Upstream {
        server: String,
        message: String,
    },
    TransportDead {
        server: String,
        reason: String,
    },
    ToolError {
        server: String,
        tool: String,
        message: String,
    },
    RateLimit(String),
    Internal(Error),
}

Canonical error type for Forge dispatcher operations.

All variants are #[non_exhaustive] to allow future additions without breaking downstream code.

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.

ServerNotFound(String)

The requested server does not exist in the router.

ToolNotFound

The requested tool does not exist on the specified server.

Fields

server: String

The server that was queried.

tool: String

The tool name that was not found.

Timeout

The operation timed out.

Fields

server: String

The server that timed out.

timeout_ms: u64

The timeout duration in milliseconds.

CircuitOpen(String)

The circuit breaker for this server is open.

GroupPolicyDenied

A group isolation policy denied the operation.

Fields

reason: String

Explanation of why the policy denied access.

Upstream

An upstream MCP server returned an error at the transport or RPC level.

This indicates a potential server health issue (connection refused, broken pipe, JSON-RPC protocol error). The server may be down or malfunctioning.

Fields

server: String

The server that returned the error.

message: String

The error message from the upstream server.

TransportDead

The transport to the server has died permanently (pipe broken, channel closed). Unlike Upstream (transient), this requires reconnection before further calls succeed.

Fields

server: String

The server whose transport died.

reason: String

Description of the transport failure.

ToolError

A tool returned an application-level error (MCP isError: true).

The downstream server is healthy — the tool processed the request but returned an error (e.g., bad parameters, missing prerequisite state). This does NOT indicate a server health issue.

Fields

server: String

The server that hosted the tool.

tool: String

The tool that returned the error.

message: String

The error message from the tool.

RateLimit(String)

A rate limit was exceeded.

Internal(Error)

An internal error (catch-all for unexpected failures).

Implementations

impl DispatchError

pub fn code(&self) -> &'static str

Returns a static error code string for programmatic matching.

pub fn trips_circuit_breaker(&self) -> bool

Whether this error indicates the server is unhealthy and should count toward the circuit breaker failure threshold.

Returns true for errors suggesting the server is down or unresponsive (Timeout, Upstream transport/RPC failures, Internal). Returns false for errors where the server responded coherently but the request was invalid (ToolError, ToolNotFound, etc).

pub fn retryable(&self) -> bool

Returns whether the operation that produced this error may succeed if retried.

pub fn to_structured_error(&self, known_tools: Option<&[(&str, &str)]>) -> Value

Convert to a structured JSON error response for LLM consumption.

Returns a JSON object with error, code, message, retryable, and optionally suggested_fix (populated by fuzzy matching when known_tools is provided for ToolNotFound errors).

Arguments

• known_tools - Optional list of (server, tool) pairs for fuzzy matching. Only used for ToolNotFound errors.

Trait Implementations

impl Debug for DispatchError

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

Formats the value using the given formatter.

impl Display for DispatchError

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

Formats the value using the given formatter.

impl Error for DispatchError

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 DispatchError

fn from(source: Error) -> Self

Converts to this type from the input type.