RetryMiddleware doesn't retry tool errors because FastMCP wraps exceptions before middleware sees them

[strawgate]

Description

RetryMiddleware doesn't work for tool calls because FastMCP's call_tool() wraps raw exceptions as ToolError before control returns to the middleware. The middleware's _should_retry() checks isinstance(error, retry_exceptions) but receives ToolError, not the original ConnectionError/TimeoutError.

The ErrorHandlingMiddleware handles this correctly by checking error.__cause__, but RetryMiddleware doesn't.

Reproduction

from fastmcp import FastMCP
from fastmcp.client import Client
from fastmcp.server.middleware.error_handling import RetryMiddleware

call_count = 0

mcp = FastMCP('test')
mcp.add_middleware(RetryMiddleware(max_retries=3, base_delay=0.01, retry_exceptions=(ConnectionError,)))

@mcp.tool
def always_fail() -> str:
    global call_count
    call_count += 1
    raise ConnectionError('connection refused')

async with Client(mcp) as client:
    try:
        await client.call_tool('always_fail')
    except:
        pass

print(f'Tool called {call_count} times')
# Prints: 1 (expected 4 with 3 retries)

Root Cause

In call_tool() (server.py line 1169-1185), all non-FastMCPError exceptions are caught and re-raised as ToolError(...) from e. This happens inside the middleware chain, so the middleware receives ToolError with __cause__=ConnectionError. The _should_retry method only checks the top-level error type.

Suggested Fix

Update RetryMiddleware._should_retry to also check error.__cause__:

def _should_retry(self, error: Exception) -> bool:
    if isinstance(error, self.retry_exceptions):
        return True
    if error.__cause__ is not None and isinstance(error.__cause__, self.retry_exceptions):
        return True
    return False

Note: ErrorHandlingMiddleware._transform_error already handles this correctly (line 92: error_type = type(error.__cause__) if error.__cause__ else type(error)).

[marvin-context-protocol]

Claude finished @strawgate's task in 2m 40s —— View job

---

Triage: RetryMiddleware doesn't check __cause__ for retry decisions

Confirmed bug. The issue is accurate and the root cause is correctly diagnosed. The fix is a one-line change to _should_retry.

• Read relevant source files
• Verify the reported behavior and root cause
• Check existing tests for RetryMiddleware
• Provide recommendation and detailed action plan

Recommendation

Update RetryMiddleware._should_retry to check error.__cause__, matching the existing pattern in ErrorHandlingMiddleware._transform_error (line 92). This is a minimal, low-risk fix.

Findings

Execution flow confirmed:

1. Tool function raises ConnectionError
2. server.py:1169 catches it as Exception as e
3. server.py:1185 re-raises as ToolError(f"Error calling tool {name!r}: {e}") from e
4. RetryMiddleware.on_request catches ToolError
5. _should_retry(ToolError) returns False because ToolError is not in retry_exceptions
6. No retry happens

The same wrapping applies to ResourceError and PromptError in their respective code paths, so this bug affects retries for all MCP object types, not just tools.

ErrorHandlingMiddleware already handles this correctly at line 92:

error_type = type(error.__cause__) if error.__cause__ else type(error)

The existing integration tests for RetryMiddleware don't assert on retry count for tool calls — they use fail_rate randomization, so the bug was not caught.

Verification

I ran a reproduction script that confirms all three aspects:

[Cause test] _should_retry(ToolError with __cause__=ConnectionError) = False (expected True)
[Fix test] Proposed fix handles all cases correctly
[Bug test] Tool called 1 times (expected 4 with retries, got 1)

• _should_retry returns False for a ToolError wrapping a ConnectionError
• The proposed fix correctly returns True for wrapped exceptions and False for non-matching causes
• End-to-end, the tool is only called once (no retries) when it should be called 4 times

Detailed Action Plan

1. Fix _should_retry in src/fastmcp/server/middleware/error_handling.py (line 183-185)

Replace:

def _should_retry(self, error: Exception) -> bool:
    """Determine if an error should trigger a retry."""
    return isinstance(error, self.retry_exceptions)

With:

def _should_retry(self, error: Exception) -> bool:
    """Determine if an error should trigger a retry."""
    if isinstance(error, self.retry_exceptions):
        return True
    if error.__cause__ is not None and isinstance(error.__cause__, self.retry_exceptions):
        return True
    return False

2. Add unit tests in tests/server/middleware/test_error_handling.py

Add to TestRetryMiddleware:

• test_should_retry_wrapped_error_true — a ToolError with __cause__=ConnectionError should return True
• test_should_retry_wrapped_error_false — a ToolError with __cause__=ValueError should return False (when retry_exceptions=(ConnectionError,))
• test_should_retry_no_cause — a plain ToolError (no __cause__) should return False

3. Add an integration test

Add a test to TestRetryMiddlewareIntegration that uses a deterministic call counter (like the reproduction in the issue) to assert the tool is called max_retries + 1 times when it raises a retryable exception. The existing integration tests use random fail_rate which is non-deterministic and didn't catch this bug.

4. Run checks

uv run pytest tests/server/middleware/test_error_handling.py -v
uv run prek run --all-files

Related Files

File	Relevance	Lines
src/fastmcp/server/middleware/error_handling.py	Contains both RetryMiddleware._should_retry (the bug) and ErrorHandlingMiddleware._transform_error (the working pattern)	183-185, 92
src/fastmcp/server/server.py	Where exceptions are wrapped as ToolError(...) from e	1169-1185
tests/server/middleware/test_error_handling.py	Existing tests — needs new cases for __cause__ checking and a deterministic integration test	284-361
src/fastmcp/exceptions.py	Defines ToolError(FastMCPError)	27-28

---

Marvin Context Protocol | Type /marvin to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

[marvin-context-protocol]

Found 3 possible duplicate issues:

1. Possibility of removing ToolError wrapping for more fine-grained exception control #1967: Possibility of removing ToolError wrapping for more fine-grained exception control
2. Call tool middleware #1988: Call tool middleware
3. ErrorHandlingMiddleware if not transforming errors to MCP #2673: ErrorHandlingMiddleware if not transforming errors to MCP

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment