crewAIInc/crewAI · error · MergeAgentHandlerToolError

API Error: {error_msg}

Error message

API Error: {error_msg}

What it means

The Merge Agent Handler endpoint speaks JSON-RPC 2.0 over HTTP; when a 2xx response body contains an "error" object, _make_mcp_request extracts error.message (and logs the code) and re-raises it wrapped in MergeAgentHandlerToolError as "API Error: ...". This means transport succeeded but the server rejected the call — bad method, invalid params, unknown tool name, or auth/permission issues at the RPC layer.

Source

Thrown at lib/crewai-tools/src/crewai_tools/tools/merge_agent_handler_tool/merge_agent_handler_tool.py:107

        }

        if params:
            payload["params"] = params

        logger.debug(f"MCP Request to {url}: {json.dumps(payload, indent=2)}")

        try:
            response = requests.post(url, json=payload, headers=headers, timeout=60)
            response.raise_for_status()
            result = response.json()

            if "error" in result:
                error_msg = result["error"].get("message", "Unknown error")
                error_code = result["error"].get("code", -1)
                logger.error(
                    f"Agent Handler API error (code {error_code}): {error_msg}"
                )
                raise MergeAgentHandlerToolError(f"API Error: {error_msg}")

            return cast(dict[str, Any], result)

        except requests.exceptions.RequestException as e:
            logger.error(f"Failed to call Agent Handler API: {e!s}")
            raise MergeAgentHandlerToolError(
                f"Failed to communicate with Agent Handler API: {e!s}"
            ) from e

    def _run(self, **kwargs: Any) -> Any:
        """Execute the Agent Handler tool with the given arguments."""
        try:
            logger.info(f"Executing {self.tool_name} with arguments: {kwargs}")

            result = self._make_mcp_request(
                method="tools/call",
                params={"name": self.tool_name, "arguments": kwargs},
            )

View on GitHub (pinned to 754d7323be)

Solutions

1. List valid tools first via MergeAgentHandlerTool.from_tool_name / a tools/list call and use an exact tool name
2. Verify tool_pack_id and registered_user_id match the Merge dashboard values
3. Check the logged error code (logger.error prints it) and rotate AGENT_HANDLER_API_KEY if it indicates auth failure
4. Print the kwargs you send and compare against the tool's inputSchema from tools/list

Example fix

# before
tool = MergeAgentHandlerTool.from_tool_name(
    tool_name="list_invoices",  # wrong name
    tool_pack_id=PACK_ID, registered_user_id=UID,
)

# after
# discover exact names first
# tools/list -> [{"name": "invoices-list", "inputSchema": {...}}, ...]
tool = MergeAgentHandlerTool.from_tool_name(
    tool_name="invoices-list",
    tool_pack_id=PACK_ID, registered_user_id=UID,
)

# Verify the tool name exists before calling it
names = {t["name"] for t in discover_tool_pack(PACK_ID, UID)}
assert desired_tool_name in names, f"unknown tool; available: {sorted(names)}"

from crewai_tools.tools.merge_agent_handler_tool.merge_agent_handler_tool import MergeAgentHandlerToolError

try:
    result = tool._run(**kwargs)
except MergeAgentHandlerToolError as e:
    if str(e).startswith("API Error:"):
        # server rejected the RPC call: log and surface, do not retry blindly
        logging.error("Agent Handler rejected call: %s", e)
        raise
    raise

When it happens

Trigger: Calling _run with a tool_name not present in the tool pack (tools/call with unknown name); malformed MCP params; wrong tool_pack_id or registered_user_id in the URL; expired/invalid AGENT_HANDLER_API_KEY causing an RPC-level error object.

Common situations: Typos in tool_name; tool pack re-published under a new id; a registered user token revoked; passing arguments that fail the remote tool's schema validation.

Related errors

• Failed to fetch tools from Agent Handler Tool Pack
• AGENT_HANDLER_API_KEY environment variable is required. Set
• Failed to communicate with Agent Handler API: {e!s}
• Tool execution failed: {e!s}
• Failed to load Tool Pack: {e!s}

AI-assisted analysis of crewAIInc/crewAI@754d7323be (2026-08-15). Data as JSON: /api/errors/b583faaa069be21d. Report an issue: GitHub.