Enum Error 

#[non_exhaustive]
pub enum Error {
    LspInitFailed {
        message: String,
    },
    LspServerError {
        code: i32,
        message: String,
        data: Option<Value>,
    },
    McpServer(String),
    DocumentNotFound(PathBuf),
    NoServerForLanguage(String),
    NoServerForTool {
        language_id: String,
        tool: ToolKind,
    },
    ServerInitializing {
        server_id: ServerId,
    },
    WorkspaceServersInitializing,
    NoServerConfigured,
    NoServerForWorkspaceTool {
        tool: ToolKind,
    },
    ConfigNotFound(PathBuf),
    InvalidConfig(String),
    Io(Error),
    Json(Error),
    TomlDe(Error),
    TomlSer(Error),
    Transport(String),
    Timeout(u64),
    ServerSpawnFailed {
        command: String,
        source: Error,
    },
    LspProtocolError(String),
    InvalidUri(String),
    ServerTerminated,
    ServerUnavailable {
        server_id: ServerId,
        reason: String,
    },
    InvalidToolParams(String),
    FileIo {
        path: PathBuf,
        source: Error,
    },
    PathOutsideWorkspace(PathBuf),
    NoWorkspaceRoots(PathBuf),
    DocumentLimitExceeded {
        current: usize,
        max: usize,
    },
    SubscriptionLimitReached {
        max: usize,
    },
    FileSizeLimitExceeded {
        size: u64,
        max: u64,
    },
    NotARegularFile(PathBuf),
    AllServersFailedToInit {
        count: usize,
        failures: Vec<ServerSpawnFailure>,
    },
    NoServersAvailable(String),
    CapabilityNotSupported {
        server_id: ServerId,
        capability: &'static str,
    },
    WorkspaceIndexing {
        server_id: ServerId,
        elapsed_secs: u64,
    },
}

The main error type for mcpls-core operations.

This enum is #[non_exhaustive]: downstream crates that match on it must include a wildcard arm. New variants (such as Error::ServerInitializing) can then be added without further breaking changes.

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.

LspInitFailed

LSP server failed to initialize.

Fields

message: String

Description of the initialization failure.

LspServerError

LSP server returned an error response.

Fields

code: i32

JSON-RPC error code.

message: String

Raw error message from the server, kept verbatim for diagnostics (logging, Debug, pattern matching). The Display impl for this variant rewrites known-internal upstream text before it reaches an MCP caller, so this field is not always what the caller sees.

data: Option<Value>

Optional additional data from the JSON-RPC error object.

McpServer(String)

MCP server error.

DocumentNotFound(PathBuf)

Document was not found or could not be opened.

NoServerForLanguage(String)

No LSP server configured for the given language.

NoServerForTool

A server is configured for the language, but no server claims this specific tool (either no server lists it in handles and there is no catch-all, or the server that claimed it failed to spawn with no live catch-all to rebind to).

Fields

language_id: String

Language ID the request was for.

tool: ToolKind

Tool that no server claims.

ServerInitializing

LSP server for the language is configured but still initializing.

Fields

server_id: ServerId

Routing identity of the server that has not yet registered.

WorkspaceServersInitializing

A workspace-wide tool (one with no file to resolve a language from, e.g. workspace_symbol_search) could not be routed because at least one expected LSP server has not registered yet. Unlike Error::ServerInitializing, resolution never narrowed down to a single candidate server, so no server_id is available.

NoServerConfigured

No LSP server is currently configured.

NoServerForWorkspaceTool

At least one server is configured somewhere in the workspace, but none of them claims a workspace-wide tool that has no file to resolve a language from (e.g. workspace_symbol_search). The language-less counterpart of Error::NoServerForTool.

Fields

tool: ToolKind

Tool that no server claims anywhere in the workspace.

ConfigNotFound(PathBuf)

Configuration file not found.

InvalidConfig(String)

Invalid configuration format.

Io(Error)

I/O error.

Json(Error)

JSON serialization/deserialization error.

TomlDe(Error)

TOML deserialization error.

TomlSer(Error)

TOML serialization error.

Transport(String)

LSP client transport error.

Timeout(u64)

Request timeout.

ServerSpawnFailed

LSP server failed to spawn.

Fields

command: String

Command that failed to spawn.

source: Error

Underlying IO error.

LspProtocolError(String)

LSP protocol error during message parsing.

InvalidUri(String)

Invalid URI format.

ServerTerminated

Server process terminated unexpectedly.

ServerUnavailable

A crashed server could not be automatically respawned.

Distinct from Self::ServerTerminated so a caller (or a log reader) can tell “the connection just died” apart from “mcpls tried to bring it back and could not” – e.g. no respawn config was ever registered for it, or it is crash-looping and is being backed off.

Fields

server_id: ServerId

Routing identity of the server that could not be respawned.

reason: String

Human-readable reason the respawn did not proceed.

InvalidToolParams(String)

Invalid tool parameters provided.

FileIo

File I/O error occurred.

See Error::mcp_error_kind for the JSON-RPC classification: a source.kind() == ErrorKind::NotFound failure – whether path was freshly supplied in this request or was tracked from an earlier one and has since been deleted/moved on disk – is caller-fault; any other IO failure is not.

Fields

path: PathBuf

Path to the file.

source: Error

Underlying I/O error.

PathOutsideWorkspace(PathBuf)

Path is outside allowed workspace boundaries.

NoWorkspaceRoots(PathBuf)

No workspace roots are configured, so path-taking operations are rejected outright rather than allowed unrestricted (fail closed).

DocumentLimitExceeded

Document limit exceeded.

Fields

current: usize

Current number of documents.

max: usize

Maximum allowed documents.

SubscriptionLimitReached

Resource-subscription limit exceeded for the session.

See Error::mcp_error_kind for the JSON-RPC classification: same shape as Self::DocumentLimitExceeded – fires on aggregate per-session tracker state, not this request’s params – so it is classified the same way, not InvalidParams.

Fields

max: usize

Maximum number of subscriptions allowed per session.

FileSizeLimitExceeded

File size limit exceeded.

Fields

size: u64

Actual file size.

max: u64

Maximum allowed size.

NotARegularFile(PathBuf)

Path exists but does not refer to a regular file (e.g. a FIFO or a character/block device).

mcpls refuses to read such paths: their reported size does not bound how much data reading them could produce, and opening some of them for reading can block indefinitely waiting for a peer. A Unix domain socket special file is not covered by this variant – open(2) on one fails outright (ENXIO) before the file-type check that produces this error ever runs, so it surfaces as Self::FileIo instead.

AllServersFailedToInit

All configured LSP servers failed to initialize.

Fields

count: usize

Number of servers that were configured.

failures: Vec<ServerSpawnFailure>

Details of each failure.

NoServersAvailable(String)

No LSP servers available (none configured or all failed).

CapabilityNotSupported

The server routed for this request does not advertise support for the requested LSP capability (e.g. no renameProvider in its ServerCapabilities).

Fields

server_id: ServerId

Routing identity of the server that lacks the capability.

capability: &'static str

The missing LSP capability’s name (e.g. "renameProvider"), the ServerCapabilities field mcpls checked.

WorkspaceIndexing

The routed server has an active signal indicating its initial workspace-load/indexing phase is still in progress, and the bounded wait for it to finish elapsed before it completed. Returned instead of an unqualified empty/null result so a caller cannot mistake “index not ready yet” for “this position/symbol genuinely has nothing here”.

Fields

server_id: ServerId

Routing identity of the server still indexing.

elapsed_secs: u64

How long mcpls waited for readiness before giving up.

Implementations

impl Error

pub fn mcp_error_kind(&self) -> McpErrorKind

Classify this error for JSON-RPC error-code mapping.

Matched exhaustively with no wildcard arm: a newly added Error variant must be given an explicit classification here instead of silently defaulting to McpErrorKind::Internal.

Examples

use mcpls_core::config::ServerId;
use mcpls_core::error::{Error, McpErrorKind};

let err = Error::WorkspaceIndexing {
    server_id: ServerId::from("rust"),
    elapsed_secs: 30,
};
let McpErrorKind::Retryable { code, data } = err.mcp_error_kind() else {
    panic!("expected a retryable classification");
};
assert_eq!(data["serverId"], "rust");

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

fn from(err: SubscriptionError) -> Self

Converts to this type from the input type.