microsoft/autogen · error · ValueError

Invalid return type: {self.server_params.return_type}

Error message

Invalid return type: {self.server_params.return_type}

What it means

HttpTool.run executes the HTTP request and then switches on server_params.return_type, accepting only 'text' or 'json'; any other value falls through to ValueError('Invalid return type: ...'). The check happens after the request has already been sent, so a bad config surfaces late — the network call succeeds and then parsing fails.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/tools/http/_http_tool.py:244

            match self.server_params.method:
                case "GET":
                    response = await client.get(url, headers=self.server_params.headers, params=model_dump)
                case "PUT":
                    response = await client.put(url, headers=self.server_params.headers, json=model_dump)
                case "DELETE":
                    response = await client.delete(url, headers=self.server_params.headers, params=model_dump)
                case "PATCH":
                    response = await client.patch(url, headers=self.server_params.headers, json=model_dump)
                case _:  # Default case POST
                    response = await client.post(url, headers=self.server_params.headers, json=model_dump)

        match self.server_params.return_type:
            case "text":
                return response.text
            case "json":
                return response.json()
            case _:
                raise ValueError(f"Invalid return type: {self.server_params.return_type}")

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Set return_type='text' or return_type='json' (lowercase) in HttpToolServerParams.
2. If you need a status code or headers, read them from the tool's structured output configuration rather than an unsupported return_type.
3. Add an assertion/guard right after constructing the params so misconfiguration fails before the request: assert params.return_type in {'text','json'}.

Example fix

# before
params = HttpToolServerParams(
    url="https://api.example.com/items",
    method="GET",
    return_type="string",  # invalid
)

# after
params = HttpToolServerParams(
    url="https://api.example.com/items",
    method="GET",
    return_type="text",
)

if params.return_type not in {"text", "json"}:
    raise ValueError(f"return_type must be 'text' or 'json', got {params.return_type!r}")
tool = HttpTool(params)

def is_valid_return_type(rt: str) -> TypeGuard[str]:
    return isinstance(rt, str) and rt in {"text", "json"}

try:
    out = await tool.run(args, cancellation_token)
except ValueError as e:
    if "Invalid return type" in str(e):
        # note: request already fired; fix config and retry
        params.return_type = "text"
    raise

When it happens

Trigger: Constructing HttpToolServerParams with return_type set to something other than 'text'/'json' — e.g. 'string', 'raw', 'binary', 'JSON', or None — then calling tool.run(). The match statement hits the default branch only after the HTTP request completes.

Common situations: Guessing the return_type vocabulary ('string', 'str', 'body') instead of reading the enum; case mismatch like 'JSON'; copy-pasting a params dict from a different tool; passing None expecting auto-detection.

Related errors

• Failed to call MCP tool
• Failed to create session
• Failed to update settings
• Failed to create team
• Failed to validate component

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/aec23f52828359fb. Report an issue: GitHub.