---
title: exceptions
sidebarTitle: exceptions
---
# `fastmcp.exceptions`
Custom exceptions for FastMCP.
## Functions
### `to_mcp_error`
```python
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`
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`
Base error for FastMCP.
### `ValidationError`
Error in validating parameters or return values.
### `ResourceError`
Error in resource operations.
### `ToolError`
Error in tool operations.
### `PromptError`
Error in prompt operations.
### `InvalidSignature`
Invalid signature for use with FastMCP.
### `ClientError`
Error in client operations.
### `NotFoundError`
Object not found.
### `DisabledError`
Object is disabled.
### `ResourceSecurityError`
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`
Error when authorization check fails.
### `InsufficientScopeError`
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.