LangChain.MCP.ErrorHandler (LangChain MCP v0.2.0)

View Source

Handles error translation from MCP to LangChain format.

MCP has three types of errors:

  1. Protocol Errors - JSON-RPC communication errors (returned as {:error, %Error{}})
  2. Transport Errors - Connection/network failures (returned as {:error, %Error{}})
  3. Domain Errors - Application-level errors (returned as {:ok, %Response{is_error: true}})

This module normalizes all error types into LangChain's error format: {:error, reason}

Examples

# Protocol error
{:error, error} = call_mcp_tool(...)
{:error, reason} = ErrorHandler.handle_error(error)
# reason: "MCP protocol error: invalid_request"

# Domain error in response
{:ok, response} = call_mcp_tool(...)
if response.is_error do
  {:error, reason} = ErrorHandler.handle_response_error(response)
  # reason: "Tool execution failed: ..."
end

# Check if error should trigger fallback
ErrorHandler.should_retry?(error)
# => true (for network errors, timeouts, etc.)
# => false (for invalid parameters, etc.)

Summary

Functions

handle_error(error)

Handles MCP protocol/transport errors and converts to LangChain format.

handle_response_error(response)

Handles MCP domain errors from responses (is_error: true).

should_retry?(arg1)

Determines if an error should trigger a fallback retry.

wrap_tool_error(error, tool_name, args)

Wraps an error with additional context about the tool call.

Functions

handle_error(error)

@spec handle_error(term()) :: {:error, String.t()}

Handles MCP protocol/transport errors and converts to LangChain format.

Parameters

  • error - Anubis.MCP.Error struct or any error term

Returns

  • {:error, String.t()} - Human-readable error message

Examples

iex> error = %Anubis.MCP.Error{code: -32600, reason: :invalid_request}
iex> ErrorHandler.handle_error(error)
{:error, "MCP protocol error (invalid_request): Invalid request format"}

handle_response_error(response)

@spec handle_response_error(map()) :: {:error, String.t()}

Handles MCP domain errors from responses (is_error: true).

Parameters

  • response - Anubis.MCP.Response struct with is_error: true

Returns

  • {:error, String.t()} - Error message from response

Examples

iex> response = %Anubis.MCP.Response{
...>   is_error: true,
...>   result: %{"isError" => true, "content" => [%{"type" => "text", "text" => "Not found"}]}
...> }
iex> ErrorHandler.handle_response_error(response)
{:error, "Tool execution failed: Not found"}

should_retry?(arg1)

@spec should_retry?(term()) :: boolean()

Determines if an error should trigger a fallback retry.

Returns true for transient errors (network, timeout, server errors) Returns false for permanent errors (invalid params, auth failures)

Parameters

  • error - Error term (Anubis.MCP.Error or other)

Returns

  • boolean() - true if should retry with fallback

Examples

iex> error = %Anubis.MCP.Error{reason: :request_timeout}
iex> ErrorHandler.should_retry?(error)
true

iex> error = %Anubis.MCP.Error{reason: :invalid_params}
iex> ErrorHandler.should_retry?(error)
false

wrap_tool_error(error, tool_name, args)

@spec wrap_tool_error({:error, term()}, String.t(), map()) :: {:error, String.t()}

Wraps an error with additional context about the tool call.

Parameters

  • error - Original error
  • tool_name - Name of the tool that failed
  • args - Arguments passed to the tool

Returns

  • {:error, String.t()} - Error with added context

Examples

iex> ErrorHandler.wrap_tool_error({:error, "timeout"}, "search", %{"query" => "test"})
{:error, "Tool 'search' failed: timeout"}