raise_on_error not forwarded during task graceful degradation

[strawgate]

Summary

When calling client.call_tool(name, task=True, raise_on_error=True) and the server doesn't support tasks (graceful degradation), raise_on_error is silently dropped. Errors are swallowed instead of raised.

Reproduction

from fastmcp import FastMCP, Client

server = FastMCP('test')

@server.tool
def failing_tool() -> str:
    """Always fails"""
    raise ValueError('intentional error')

async with Client(server) as client:
    # Non-task path: correctly raises ToolError
    await client.call_tool('failing_tool', raise_on_error=True)  # raises ✅

    # Task path with graceful degradation: should raise but doesn't
    task = await client.call_tool('failing_tool', task=True, raise_on_error=True)
    result = await task.result()
    print(result.is_error)  # True — error was silently swallowed ❌

Root Cause

call_tool() (tools.py:276) calls _call_tool_as_task() without forwarding raise_on_error:

if task:
    return await self._call_tool_as_task(
        name, arguments, task_id, ttl, meta=request_meta or None
    )
    # ← raise_on_error not passed

_call_tool_as_task() (tools.py:291) doesn't accept raise_on_error at all. In the graceful degradation path (line 351), it calls _parse_call_tool_result without it, which defaults to raise_on_error=False:

parsed_result = await self._parse_call_tool_result(name, raw_result)
# ← defaults to raise_on_error=False

Fix

1. Add raise_on_error: bool = True parameter to _call_tool_as_task()
2. Pass it through from call_tool() at line 276
3. Forward it to _parse_call_tool_result() at line 351

[marvin-context-protocol]

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

---

Recommendation

The diagnosis in the issue is correct and the proposed fix is the right shape, but it only addresses half the problem. There's a mirror bug in the same area: ToolTask.result() hardcodes raise_on_error=True when parsing results for successfully-scheduled background tasks (src/fastmcp/client/tasks.py:382, 387, 400), so raise_on_error=False is also ignored on that path.

The cleanest fix is to thread raise_on_error through ToolTask and apply it at .result() time for both paths, rather than only forwarding it to _parse_call_tool_result at the graceful-degradation call site. This makes task.result() behave identically to call_tool(task=False) and keeps the raise point consistent across scheduled and synchronous execution.

Verification

Reproduced the bug exactly as reported against main (c2dafc1):

NON-TASK: raised ToolError: Error calling tool 'failing_tool': intentional error
TASK: did not raise. is_error=True (BUG)

In-memory transport returns a McpError "does not support task-augmented execution" from the server-side task router, and the client falls through to the graceful-degradation branch at src/fastmcp/client/mixins/tools.py:349-358, where _parse_call_tool_result is called with its default raise_on_error=False.

Findings

Primary bug — src/fastmcp/client/mixins/tools.py:

• call_tool (line 275-278) does not forward raise_on_error to _call_tool_as_task.
• _call_tool_as_task (line 291-358) does not accept a raise_on_error parameter.
• Line 351 calls self._parse_call_tool_result(name, raw_result) without the flag, which defaults to False (line 168). Errors on the graceful-degradation path are silently swallowed.

Mirror bug — src/fastmcp/client/tasks.py (ToolTask.result()):

• Lines 382, 387, and 400 all pass raise_on_error=True as a hardcoded literal when parsing a background-task result. A user who called call_tool(task=True, raise_on_error=False) still gets an exception on the successfully-scheduled path. The opposite failure mode from the reported bug, but the same root cause: raise_on_error isn't carried into ToolTask.

Why the two halves matter together: fixing only the graceful-degradation path (as the issue proposes) leaves behavior inconsistent between "task accepted" and "task declined" — in the declined case the flag is honored, in the accepted case it's ignored. Users can't reason about this without knowing which branch fired.

Related: this is bug #3 from the audit in #3856 (closed as too-long), now filed as a standalone issue.

Detailed Action Plan

1. Carry raise_on_error into ToolTask — src/fastmcp/client/tasks.py:

• Add raise_on_error: bool = True to ToolTask.__init__ (line 332-349) and store as self._raise_on_error.
• In ToolTask.result() (line 351-408), replace the three hardcoded raise_on_error=True literals (lines 382, 387, 400) with self._raise_on_error.
• Also handle the _is_immediate branch (line 364-366): the immediate result has already been parsed with raise_on_error=False at construction time, so check result.is_error and, if self._raise_on_error is True, raise ToolError using the same message format as _parse_call_tool_result (src/fastmcp/client/mixins/tools.py:388-393). This defers the raise to .result() time, matching the non-graceful path.

2. Forward raise_on_error from call_tool — src/fastmcp/client/mixins/tools.py:

• Add raise_on_error: bool = True parameter to _call_tool_as_task (line 291).
• Pass raise_on_error=raise_on_error from call_tool at line 276.
• At line 351, keep the call as _parse_call_tool_result(name, raw_result) (default raise_on_error=False) — we deliberately don't raise here, because raising should happen at .result() time to match the background path. Instead, pass raise_on_error=raise_on_error into the ToolTask(...) constructor at line 353-358.

3. Tests — add to tests/client/tasks/test_client_tool_tasks.py (or create a focused file):

• Graceful degradation + raise_on_error=True → await task.result() raises ToolError with the original message.
• Graceful degradation + raise_on_error=False → await task.result() returns CallToolResult with is_error=True and does not raise.
• Background task accepted + raise_on_error=False → await task.result() returns CallToolResult with is_error=True (covers the mirror bug).
• Background task accepted + raise_on_error=True → still raises (regression guard).
• Use the in-memory transport for the graceful-degradation cases (as in the issue repro); for the accepted-task cases use a server that supports task execution (see tests/server/tasks/ for existing patterns).

4. Do not touch PromptTask or ResourceTask in this PR — the same pattern may or may not apply there, but the issue is scoped to tool tasks. A follow-up can audit those.

Keep the change small: no new abstractions, no refactor of _parse_call_tool_result. The fix is ~5 lines in each of the two files plus tests.

Related Items

Repository	Issue or PR	Relevance
PrefectHQ/fastmcp	#3856	Parent audit issue (closed as too-long); this is bug #3 from that list
PrefectHQ/fastmcp	#3632	Prior task-related fix (mounted tool task metadata) — different code path but same SEP-1686 feature area
PrefectHQ/fastmcp	#2906	Original SEP-1686 background-task implementation

Related Files

File	Relevance	Lines
src/fastmcp/client/mixins/tools.py	call_tool and _call_tool_as_task — the primary fix site	275-278, 291-358
src/fastmcp/client/tasks.py	ToolTask.result() — mirror-bug site with hardcoded raise_on_error=True	351-408
tests/client/tasks/test_client_tool_tasks.py	Existing tool-task tests — currently no raise_on_error coverage, add regression tests here

---

Marvin Context Protocol | Type /marvin to interact further

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

[marvin-context-protocol]

Found 1 possible duplicate issue:

1. Client bugs: elicitation scalar return, resource dict return, raise_on_error+task, Client.new() shared state, prompt error message #3856: Client bugs: elicitation scalar return, resource dict return, raise_on_error+task, Client.new() shared state, prompt error message

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

[gnanirahulnutakki]

I’m planning to work on this. My intended fix is to thread raise_on_error through the task path as well, including the graceful-degradation branch when the server does not support tasks, and add regression coverage for both the direct and degraded task flows so task=True preserves the same exception semantics as the non-task call. If there’s a preferred test location or any nuance around the fallback behavior that should be preserved, let me know.

[gnanirahulnutakki]

I opened a fix for this here: #3946

The patch threads raise_on_error through the tool-task path and also fixes the accepted background-task branch so ToolTask.result() respects the caller's requested error behavior instead of hardcoding True. It includes regression coverage for both graceful degradation and accepted task execution.