Tool error handling

When calling tools from your , smart error handling is crucial for creating robust and reliable applications. This guide covers everything you need to know about handling errors from a ’s perspective.

Error handling philosophy

Arcade’s error handling is designed to provide you with as much information as possible about the error that occurred. When an error occurs, Arcade’s Engine will return a structured error object that you can use to understand the error and take appropriate action.

Error hierarchy

Arcade uses a structured error hierarchy to categorize different types of errors.


ToolkitError                                  # (Abstract base class)
├── ToolkitLoadError                          # Occurs during MCP Server import
└── ToolError                                 # (Abstract)
    ├── ToolDefinitionError                    # Detected when tool is added to catalog
    │   ├── ToolInputSchemaError              # Invalid input parameter types/annotations
    │   └── ToolOutputSchemaError             # Invalid return type annotations
    └── ToolRuntimeError                      # Errors during tool execution
        ├── ToolSerializationError            # (Abstract)
        │   ├── ToolInputError                # JSON to Python conversion fails
        │   └── ToolOutputError               # Python to JSON conversion fails
        └── ToolExecutionError                # Errors during tool execution
            ├── RetryableToolError            # Tool can be retried with extra context
            ├── ContextRequiredToolError      # Additional context needed before retry
            ├── FatalToolError                # Unhandled bugs in the tool implementation
            └── UpstreamError                 # HTTP/API errors from external services
                └── UpstreamRateLimitError    # Rate limiting errors from service

Client error handling examples

Here’s how to handle different types of output errors when executing with Arcade’s client libraries:

Python


"""
This example demonstrates how to handle different kinds of output errors when executing a tool.
"""
 
from arcadepy import Arcade  # pip install arcadepy
from arcadepy.types.execute_tool_response import OutputError
 
 
# Requires arcadepy >= 1.8.0
def handle_tool_error(error: OutputError) -> None:
    """Example of how to identify different kinds of output errors."""
    error_kind = error.kind
    if error_kind == OutputError.Kind.TOOL_RUNTIME_BAD_INPUT_VALUE:
        # You provided the executed tool with an invalid input value
        print(error.message)
    elif error_kind == OutputError.Kind.TOOL_RUNTIME_RETRY:
        # The tool returned a retryable error. Provide the additional
        # prompt content to the LLM and retry the tool call
        instructions_for_llm = error.additional_prompt_content
        print(instructions_for_llm)
    elif error_kind == OutputError.Kind.TOOL_RUNTIME_CONTEXT_REQUIRED:
        # The tool requires extra context from the user or orchestrator.
        # Provide the additional prompt content to them and then retry the
        # tool call with the new context
        request_for_context = error.additional_prompt_content
        print(request_for_context)
    elif error_kind == OutputError.Kind.TOOL_RUNTIME_FATAL:
        # The tool encountered a fatal error during execution
        print(error.message)
    elif error_kind == OutputError.Kind.UPSTREAM_RUNTIME_RATE_LIMIT:
        # The tool encountered a rate limit error from an upstream service
        # Wait for the specified amount of time and then retry the tool call
        seconds_to_wait = error.retry_after_ms / 1000
        print(f"Wait for {seconds_to_wait} seconds before retrying the tool call")
    elif error_kind.startswith("UPSTREAM_"):
        # The tool encountered an error from an upstream service
        print(error.message)
 
 
client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable
user_id = "{arcade_user_id}"
tool_name = "Reddit.GetPostsInSubreddit"
tool_input = {"subreddit": "programming", "limit": 1}
 
# Go through the OAuth flow for the tool
auth_response = client.tools.authorize(
    tool_name=tool_name,
    user_id=user_id,
)
if auth_response.status != "completed":
    print(f"Click this link to authorize: {auth_response.url}")
 
client.auth.wait_for_completion(auth_response)
 
# Execute the tool
response = client.tools.execute(
    tool_name=tool_name,
    input=tool_input,
    user_id=user_id,
    include_error_stacktrace=True,
)
if response.output.error:
    handle_tool_error(response.output.error)

JavaScript


/**
 * This example demonstrates how to handle different kinds of output errors when executing a tool.
 */
 
import { Arcade } from "@arcadeai/arcadejs"; // npm install @arcadeai/arcadejs
 
// Requires @arcadeai/arcadejs >= 1.10.0
function handleToolError(error) {
  const errorKind = error.kind;
  if (errorKind === "TOOL_RUNTIME_BAD_INPUT_VALUE") {
    // You provided the executed tool with an invalid input value
    console.log(error.message);
  } else if (errorKind === "TOOL_RUNTIME_RETRY") {
    // The tool returned a retryable error. Provide the additional
    // prompt content to the LLM and retry the tool call
    const instructionsForLLM = error.additional_prompt_content;
    console.log(instructionsForLLM);
  } else if (errorKind === "TOOL_RUNTIME_CONTEXT_REQUIRED") {
    // The tool requires extra context from the user or orchestrator.
    // Provide the additional prompt content to them and then retry the
    // tool call with the new context
    const requestForContext = error.additional_prompt_content;
    console.log(requestForContext);
  } else if (errorKind === "TOOL_RUNTIME_FATAL") {
    // The tool encountered a fatal error during execution
    console.log(error.message);
  } else if (errorKind === "UPSTREAM_RUNTIME_RATE_LIMIT") {
    // The tool encountered a rate limit error from an upstream service
    // Wait for the specified amount of time and then retry the tool call
    const secondsToWait = error.retry_after_ms / 1000;
    console.log(`Wait for ${secondsToWait} seconds before retrying the tool call`);
  } else if (errorKind.startsWith("UPSTREAM_")) {
    // The tool encountered an error from an upstream service
    console.log(error.message);
  }
}
 
const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable
const userId = "{arcade_user_id}";
const toolName = "Reddit.GetPostsInSubreddit";
const toolInput = { subreddit: "programming", limit: 1 };
 
// Go through the OAuth flow for the tool
const authResponse = await client.tools.authorize({
  tool_name: toolName,
  user_id: userId,
});
if (authResponse.status !== "completed") {
  console.log(`Click this link to authorize: ${authResponse.url}`);
}
 
await client.auth.waitForCompletion(authResponse);
 
// Execute the tool
const response = await client.tools.execute({
  tool_name: toolName,
  input: toolInput,
  user_id: userId,
  include_error_stacktrace: true,
});
if (response.output.error) {
  handleToolError(response.output.error);
}

Error types in Arcade client libraries

To see the full structure of an OutputError, see arcade-py OutputError and arcade-js OutputError .

Error types in MCP clients

As of now, Clients do not return structured error information, only an error message. Arcade will attempt to include the type of error in the error message, but it is not guaranteed.

Best practices

Let Arcade handle most errors: There’s no need to wrap your logic in try/catch blocks unless you need custom error handling.
Use specific error types: When you do need to raise errors explicitly, use the most specific error type available.
Include additional : For RetryableToolError and ContextRequiredToolError, use the additional_prompt_content parameter to guide the LLM or .

Building tools with error handling

To learn more about how to build with error handling, see the Build Tools section.