Skip to content

page.mdx

Latest commit

 

History

History
266 lines (174 loc) · 5.48 KB

page.mdx

File metadata and controls

266 lines (174 loc) · 5.48 KB
title Errors - Arcade MCP Python Reference
description Domain-specific error types raised by the MCP server and components

import { Callout } from "nextra/components";

Errors

Domain-specific error types raised by the MCP server and components.

arcade_mcp_server.exceptions

MCP Exception Hierarchy

Provides domain-specific exceptions for better error handling and debugging.

MCPError

Bases: Exception

Base error for all MCP-related exceptions.

MCPRuntimeError

Bases: MCPError

Runtime error for all MCP-related exceptions.

MCPContextError

Bases: MCPError

Error in context management.

ServerError

Bases: MCPRuntimeError

Error in server operations.

AuthorizationError

Bases: MCPContextError

Authorization failure.

LifespanError

Bases: ServerError

Error in lifespan management.

NotFoundError

Bases: MCPContextError

Requested entity not found.

PromptError

Bases: MCPContextError

Error in prompt management.

ProtocolError

Bases: MCPRuntimeError

Error in MCP protocol handling.

RequestError

Bases: ServerError

Error in request processing from client to server.

ResourceError

Bases: MCPContextError

Error in resource management.

ResponseError

Bases: ServerError

Error in request processing from server to client.

ServerRequestError

Bases: RequestError

Error in sending request from server to client initiated by the server.

SessionError

Bases: ServerError

Error in session management.

TransportError

Bases: MCPRuntimeError

Error in transport layer (stdio, HTTP, etc).

arcade_core.errors

Tool execution errors with retry semantics. Re-exported via arcade_mcp_server.exceptions.

RetryableToolError

Bases: ToolExecutionError

The operation failed but can be retried.

from arcade_mcp_server.exceptions import RetryableToolError

# Simple retry
raise RetryableToolError("Service temporarily unavailable")

# With retry delay
raise RetryableToolError(
    "Rate limited",
    retry_after_ms=5000
)

# With guidance for the AI
raise RetryableToolError(
    "Search returned no results",
    additional_prompt_content="Try broader search terms or check spelling."
)

FatalToolError

Bases: ToolExecutionError

Unrecoverable error — the AI should not retry.

from arcade_mcp_server.exceptions import FatalToolError

raise FatalToolError("Account has been permanently deleted")

# With developer-only details
raise FatalToolError(
    "Configuration error",
    developer_message="Missing required API key in environment"
)

ContextRequiredToolError

Bases: ToolExecutionError

The operation needs additional context from the user before it can proceed.

from arcade_mcp_server.exceptions import ContextRequiredToolError

raise ContextRequiredToolError(
    "Multiple users found matching 'John'",
    additional_prompt_content="Please specify: John Smith (john@work.com) or John Doe (john@home.com)"
)

UpstreamError

Bases: ToolExecutionError

Error from an external API or service.

from arcade_mcp_server.exceptions import UpstreamError

raise UpstreamError(
    "Slack API error: channel_not_found",
    status_code=404
)

UpstreamRateLimitError

Bases: UpstreamError

Rate limit from an external API. Includes retry information.

from arcade_mcp_server.exceptions import UpstreamRateLimitError

raise UpstreamRateLimitError(
    "Rate limited by Slack",
    retry_after_ms=60_000
)
You rarely throw `UpstreamError` manually. Use [error adapters](/references/mcp/python/types#error-adapters) to automatically translate SDK errors.

Error Hierarchy

MCPError (base)
├── MCPContextError (user/input caused the error)
│   ├── AuthorizationError
│   ├── NotFoundError
│   ├── PromptError
│   └── ResourceError
└── MCPRuntimeError (server/infrastructure caused the error)
    ├── ProtocolError
    ├── TransportError
    └── ServerError
        ├── RequestError
        │   └── ServerRequestError
        ├── ResponseError
        ├── SessionError
        └── LifespanError

ToolkitError (base for tool errors)
└── ToolError
    └── ToolRuntimeError
        └── ToolExecutionError
            ├── RetryableToolError (can retry)
            ├── FatalToolError (do not retry)
            ├── ContextRequiredToolError (needs user input)
            └── UpstreamError (external API failure)
                └── UpstreamRateLimitError

Examples

Raising exceptions for common error scenarios

from arcade_mcp_server.exceptions import (
    NotFoundError,
    RetryableToolError,
    FatalToolError,
)

# Resource not found
async def read_resource_or_fail(uri: str) -> str:
    if not await exists(uri):
        raise NotFoundError(f"Resource not found: {uri}")
    return await read(uri)

# Retryable failure
async def fetch_data(url: str):
    try:
        return await http_client.get(url)
    except ConnectionError as e:
        raise RetryableToolError(
            "Failed to connect. Please try again.",
            developer_message=str(e)
        )

# Unrecoverable failure
def validate_config(config: dict):
    if "api_key" not in config:
        raise FatalToolError("Missing required configuration: api_key")