microsoft/autogen · error · AssertionError

Return type not found

Error message

Return type not found

What it means

The @message_handler decorator requires a resolvable return type annotation because it records produces_types (and serializes RPC responses). get_type_hints found no 'return' entry or get_types() could not extract a concrete type from it, so the decorator aborts at import/decoration time.

Source

Thrown at python/packages/autogen-core/src/autogen_core/_routed_agent.py:137

        func: Callable[[AgentT, ReceivesT, MessageContext], Coroutine[Any, Any, ProducesT]],
    ) -> MessageHandler[AgentT, ReceivesT, ProducesT]:
        type_hints = get_type_hints(func)
        if "message" not in type_hints:
            raise AssertionError("message parameter not found in function signature")

        if "return" not in type_hints:
            raise AssertionError("return parameter not found in function signature")

        # Get the type of the message parameter
        target_types = get_types(type_hints["message"])
        if target_types is None:
            raise AssertionError("Message type not found")

        # print(type_hints)
        return_types = get_types(type_hints["return"])

        if return_types is None:
            raise AssertionError("Return type not found")

        # Convert target_types to list and stash

        @wraps(func)
        async def wrapper(self: AgentT, message: ReceivesT, ctx: MessageContext) -> ProducesT:
            if type(message) not in target_types:
                if strict:
                    raise CantHandleException(f"Message type {type(message)} not in target types {target_types}")
                else:
                    logger.warning(f"Message type {type(message)} not in target types {target_types}")

            return_value = await func(self, message, ctx)

            if AnyType not in return_types and type(return_value) not in return_types:
                if strict:
                    raise ValueError(f"Return type {type(return_value)} not in return types {return_types}")
                else:
                    logger.warning(f"Return type {type(return_value)} not in return types {return_types}")

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Add an explicit return annotation: '-> MyResponseType' for @rpc/@message_handler handlers
2. Annotate fire-and-forget handlers with '-> None' (required for @event handlers)
3. Ensure any string/forward-referenced return type is importable at runtime so get_type_hints resolves it

Example fix

# before
@message_handler
async def handle(self, message: Msg, ctx: MessageContext): ...

# after
@message_handler
async def handle(self, message: Msg, ctx: MessageContext) -> Response: ...

from typing import get_type_hints

def handler_has_return_hint(func) -> bool:
    return "return" in get_type_hints(func)

def has_return_annotation(func) -> bool:
    return get_type_hints(func).get("return") is not None

When it happens

Trigger: A handler declared as async def handle(self, message: Msg, ctx: MessageContext) with no return annotation, or annotated with an unresolvable forward reference / unsupported generic so get_types returns None.

Common situations: Omitting '-> ...' because Python does not require it; converting a sync callback that returned nothing into an event-style handler; string return annotations referencing types not importable at runtime.

Related errors

• Message type not found
• Message type not found. Please provide a type hint for the m
• Return type not found. Please use `None` as the type hint of
• Invalid arguments
• No serializers found for type {type}. Please provide an expl

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