> ## Documentation Index
> Fetch the complete documentation index at: https://gofastmcp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# exceptions

# `fastmcp.exceptions`

Custom exceptions for FastMCP.

## Functions

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

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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

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

Base error for FastMCP.

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

Error in validating parameters or return values.

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

Error in resource operations.

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

Error in tool operations.

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

Error in prompt operations.

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

Invalid signature for use with FastMCP.

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

Error in client operations.

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

Object not found.

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

Object is disabled.

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

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` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Error when authorization check fails.

### `InsufficientScopeError` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/exceptions.py#L93" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Authorization failed because the token is missing required OAuth scopes.

Unlike a bare `AuthorizationError`, this carries the specific scopes the
caller must obtain. A component-level scope shortfall can then be signalled
as a spec-correct `insufficient_scope` step-up (SEP-2350 / RFC 6750 §3),
naming exactly what to re-authorize for instead of an opaque denial. The
named scopes are only the *unmet* ones, so an existing grant is accumulated
rather than replaced when the caller re-authorizes.