fastmcp.exceptions

Custom exceptions for FastMCP.

Functions

to_mcp_error ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

to_mcp_error(exc: Exception) -> MCPError

Translate a FastMCP exception into a wire-format MCPError.

Central mapping from FastMCP's public exception types to the JSON-RPC error codes defined by the MCP spec (imported from mcp_types). Request-handler adapters call this instead of hand-rolling MCPError(code=..., ...) per call site, so the wire codes stay spec-correct and consistent across resources, prompts, and tools.

NotFoundError and DisabledError map to INVALID_PARAMS (-32602): per SEP-2164 a request naming a component that does not exist (or is disabled) is an invalid-params error, which matches the SDK's own ResourceNotFoundError -> INVALID_PARAMS mapping in mcp.server.mcpserver. ValidationError is also an invalid-params error. Everything else falls back to default_code (INTERNAL_ERROR by default).

If exc is already an MCPError, it is returned unchanged so an explicit code chosen upstream survives translation.

Classes

FastMCPDeprecationWarning ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Deprecation warning for FastMCP APIs.

Subclass of DeprecationWarning so that standard warning filters still apply, but FastMCP can selectively enable its own warnings without affecting other libraries in the process.

FastMCPError ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L43" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Base error for FastMCP.

ValidationError ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Error in validating parameters or return values.

ResourceError ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Error in resource operations.

ToolError ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L59" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Error in tool operations.

PromptError ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Error in prompt operations.

InvalidSignature ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L67" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Invalid signature for use with FastMCP.

ClientError ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L71" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Error in client operations.

NotFoundError ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L75" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Object not found.

DisabledError ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Object is disabled.

ResourceSecurityError ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L83" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

A templated resource parameter failed path-security screening.

Subclasses NotFoundError so the read handler surfaces a non-leaky INVALID_PARAMS (-32602) "resource not found" error to the client — a traversal attempt is indistinguishable from a request for a resource that does not exist, and never reveals which parameter or policy tripped.

AuthorizationError ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L94" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Error when authorization check fails.