Enum Error 

#[non_exhaustive]
pub enum Error {
    LspInitFailed {
        phase: InitPhase,
        cause: Box<Self>,
        hint: Option<InitFailureHint>,
        stderr: Option<StderrExcerpt>,
    },
    LspServerError {
        code: i32,
        message: String,
        data: Option<Value>,
    },
    McpServerStart(Box<dyn Error + Send + Sync>),
    TaskFailed {
        task: BackgroundTask,
        source: JoinError,
    },
    StdioCapture(StdioStream),
    HttpBind {
        addr: SocketAddr,
        source: Error,
    },
    DocumentNotFound(PathBuf),
    NoServerForLanguage {
        language: LanguageId,
        file: FileKey,
        patterns: Arc<[FilePattern]>,
    },
    NoServerForTool {
        language_id: LanguageId,
        tool: ToolKind,
    },
    ServerFailedToStart(Box<ServerSpawnFailure>),
    ServerInitializing {
        server_id: ServerId,
    },
    ServerRestarted {
        server_id: ServerId,
    },
    SymbolResolution(Box<SymbolResolutionData>),
    UnknownServers {
        unknown: Vec<ServerId>,
        configured: Vec<ServerId>,
    },
    WorkspaceServersInitializing,
    NoServerConfigured,
    NoServerForWorkspaceTool {
        tool: ToolKind,
    },
    ConfigNotFound(PathBuf),
    ConfigInsideWorkspace {
        path: PathBuf,
    },
    Config(ConfigError),
    Io(Error),
    Json(Error),
    TomlDe(Error),
    TomlSer(Error),
    Timeout(Duration),
    ServerSpawnFailed {
        command: ServerCommand,
        source: Error,
    },
    ServerNotFound {
        command: ServerCommand,
        source: Error,
    },
    LspProtocolError(RedactedText),
    NoResolvableListenUris,
    InvalidPositionInput(InvalidPosition),
    InvalidRangeInput(InvalidRange),
    InvalidHierarchyItemInput(InvalidHierarchyItem),
    PositionBeyondDocument {
        line: NonZeroU32,
        last_line: NonZeroU32,
    },
    ResourceUri(ResourceUriError),
    PathToUri(PathBuf),
    ServerTerminated,
    ShutdownTimeout,
    ServerExitedDuringInit {
        command: ServerCommand,
        exit_code: Option<i32>,
        hint: Option<InitFailureHint>,
        stderr: Option<StderrExcerpt>,
    },
    ServerUnavailable {
        server_id: ServerId,
        retry_in: Duration,
    },
    InvalidToolParams(String),
    InvalidClientPath(InvalidClientPath),
    MalformedPath {
        path: PathBuf,
        source: Error,
    },
    FileIo {
        path: PathBuf,
        source: Error,
    },
    PathOutsideWorkspace(PathBuf),
    NoWorkspaceRoots(PathBuf),
    DocumentLimitExceeded {
        current: usize,
        max: NonZeroUsize,
    },
    SubscriptionLimitReached {
        max: usize,
    },
    ListenStreamsExhausted {
        max: usize,
    },
    ListenFilterTooLarge {
        max: usize,
    },
    FileSizeLimitExceeded(SizeExceeded),
    NotARegularFile(PathBuf),
    AllServersFailedToInit {
        failures: Vec<ServerSpawnFailure>,
    },
    CapabilityNotSupported {
        server_id: ServerId,
        capability: Capability,
    },
    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

phase: InitPhase

The handshake step that failed.

cause: Box<Self>

Why the step failed, so a timeout and a rejection by the server stay distinguishable. Rendered by Display instead of being exposed through source(), so the chain is not printed twice.

hint: Option<InitFailureHint>

The likely cause and remedy, when one is known.

stderr: Option<StderrExcerpt>

What the server wrote to stderr before failing, if anything.

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.

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

The MCP server could not complete its handshake with the client.

TaskFailed

A background task panicked or was cancelled.

Fields

task: BackgroundTask

The task that failed.

source: JoinError

The join failure, carrying the panic payload or cancellation.

StdioCapture(StdioStream)

A standard stream of the spawned LSP server could not be captured.

HttpBind

The HTTP transport could not bind its listener.

Fields

addr: SocketAddr

Address the listener was asked to bind.

source: Error

Underlying I/O error, e.g. AddrInUse.

DocumentNotFound(PathBuf)

Document was not found or could not be opened.

NoServerForLanguage

No LSP server configured for the given language.

Fields

language: LanguageId

The language detected for the file.

file: FileKey

What identifies the file to the language map: its extension, its extensionless name, or FileKey::Unmappable.

patterns: Arc<[FilePattern]>

The file_patterns configured across all servers, so the error can show what was available to map the extension.

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: LanguageId

Language ID the request was for.

tool: ToolKind

Tool that no server claims.

ServerFailedToStart(Box<ServerSpawnFailure>)

The server configured for this request failed to start and, because startup failures are never retried, will not become available until mcpls is restarted.

Boxed to keep Error small.

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.

ServerRestarted

The server was restarted on request while this call was in flight or being routed; the request never reached the replacement.

Fields

server_id: ServerId

Routing identity of the restarted server.

SymbolResolution(Box<SymbolResolutionData>)

A symbol name could not be resolved to exactly one position.

Boxed to keep Error small.

UnknownServers

A restart request named servers that are not configured.

Fields

unknown: Vec<ServerId>

The requested ids that matched no configured server.

configured: Vec<ServerId>

Every configured server id.

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.

ConfigInsideWorkspace

Untrusted-workspace mode refused a config file that lies inside the workspace or the current directory, because the analyzed checkout controls it. A startup error; never reaches a tool response.

Fields

path: PathBuf

The canonical path of the config file.

Config(ConfigError)

Invalid configuration.

Io(Error)

I/O error; displays the OS text once, with no prefix.

Json(Error)

JSON serialization/deserialization error.

TomlDe(Error)

TOML deserialization error.

TomlSer(Error)

TOML serialization error.

Timeout(Duration)

Request timeout, carrying the elapsed limit.

ServerSpawnFailed

LSP server failed to spawn.

Fields

command: ServerCommand

Command that failed to spawn.

source: Error

Underlying IO error.

ServerNotFound

LSP server executable was not found.

Distinct from Error::ServerSpawnFailed so the message can carry PATH and install guidance.

Fields

command: ServerCommand

Command that could not be found.

source: Error

Underlying IO error.

LspProtocolError(RedactedText)

LSP protocol error during message parsing.

NoResolvableListenUris

None of the resource URIs a subscriptions/listen request named resolves inside the workspace.

InvalidPositionInput(InvalidPosition)

A client-supplied position is out of bounds.

InvalidRangeInput(InvalidRange)

A client-supplied range is malformed or too large.

InvalidHierarchyItemInput(InvalidHierarchyItem)

A client-supplied hierarchy item has an invalid range.

PositionBeyondDocument

A client-supplied line lies beyond the end of the tracked document.

Only the line is checked: an LSP server clamps a character past the end of its line to the line length (LSP 3.17, Position), so such a character is forwarded unchanged.

Fields

line: NonZeroU32

The 1-based line the client supplied.

last_line: NonZeroU32

The 1-based number of the document’s last line.

ResourceUri(ResourceUriError)

A client-supplied lsp-diagnostics:// resource URI was rejected.

PathToUri(PathBuf)

A path mcpls itself derived could not be represented as a URI.

ServerTerminated

Server process terminated unexpectedly.

ShutdownTimeout

LSP server shutdown did not complete before its deadline.

ServerExitedDuringInit

LSP server process exited before completing the initialize handshake.

Fields

command: ServerCommand

Command that was spawned.

exit_code: Option<i32>

Exit code, or None if the process was terminated by a signal.

hint: Option<InitFailureHint>

The likely cause and remedy, when one is known.

stderr: Option<StderrExcerpt>

What the server wrote to stderr before exiting, if anything.

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” – it is crash-looping and is being backed off.

Fields

server_id: ServerId

Routing identity of the server that could not be respawned.

retry_in: Duration

Remaining backoff before the next respawn attempt.

InvalidToolParams(String)

Invalid tool parameters provided.

InvalidClientPath(InvalidClientPath)

A client-supplied file path is empty or contains a NUL byte.

MalformedPath

A client-supplied file path is malformed for the filesystem: it runs through a regular file, or has an invalid or over-long name.

Produced only while validating the client path (WorkspaceRoots::validate); the same IO kinds raised later, while reading or opening an already validated file, stay Error::FileIo because there they are environmental.

Fields

path: PathBuf

The path as supplied by the client.

source: Error

Underlying I/O error.

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: NonZeroUsize

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.

ListenStreamsExhausted

Too many concurrent subscriptions/listen streams are open.

Transient: a stream closing frees a slot, so it is classified as retryable (see Error::mcp_error_kind).

Fields

max: usize

Maximum number of concurrent listen streams.

ListenFilterTooLarge

A subscriptions/listen request asked for more resource URIs than a single stream may watch.

Fields

max: usize

Maximum number of resource URIs per listen stream.

FileSizeLimitExceeded(SizeExceeded)

File size limit exceeded.

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 from a document read and as Self::Io from the config loader.

AllServersFailedToInit

All configured LSP servers failed to initialize.

Fields

failures: Vec<ServerSpawnFailure>

Details of each failure.

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: Capability

The missing LSP capability, naming 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_static("rust"),
    elapsed_secs: 30,
};
let McpErrorKind::Retryable(data) = err.mcp_error_kind() else {
    panic!("expected a retryable classification");
};
assert_eq!(data.code(), mcpls_core::error::WORKSPACE_INDEXING_ERROR_CODE);

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

fn from(source: ConfigError) -> 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<Error> for Error

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<InvalidClientPath> for Error

fn from(source: InvalidClientPath) -> Self

Converts to this type from the input type.

impl From<InvalidHierarchyItem> for Error

fn from(source: InvalidHierarchyItem) -> Self

Converts to this type from the input type.

impl From<InvalidPosition> for Error

fn from(source: InvalidPosition) -> Self

Converts to this type from the input type.

impl From<InvalidRange> for Error

fn from(source: InvalidRange) -> Self

Converts to this type from the input type.

impl From<ResourceUriError> for Error

fn from(source: ResourceUriError) -> Self

Converts to this type from the input type.