microsoft/autogen · error · AssertionError

Message type not found. Please provide a type hint for the m

Error message

Message type not found. Please provide a type hint for the message parameter.

What it means

The @event decorator extracts target_types from the 'message' parameter's type hint; get_types() returned None, meaning the annotation is absent, None, or an unresolvable/unsupported type expression. The error message explicitly tells you to provide a type hint for the message parameter.

Source

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

        func: The function to be decorated.
        strict: If `True`, the handler will raise an exception if the message type is not in the target types. If `False`, it will log a warning instead.
        match: A function that takes the message and the context as arguments and returns a boolean. This is used for secondary routing after the message type. For handlers addressing the same message type, the match function is applied in alphabetical order of the handlers and the first matching handler will be called while the rest are skipped. If `None`, the first handler in alphabetical order matching the same message type will be called.
    """

    def decorator(
        func: Callable[[AgentT, ReceivesT, MessageContext], Coroutine[Any, Any, None]],
    ) -> MessageHandler[AgentT, ReceivesT, None]:
        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. Please provide a type hint for the message parameter.")

        return_types = get_types(type_hints["return"])

        if return_types is None:
            raise AssertionError("Return type not found. Please use `None` as the type hint of the return type.")

        # Convert target_types to list and stash

        @wraps(func)
        async def wrapper(self: AgentT, message: ReceivesT, ctx: MessageContext) -> None:
            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)  # type: ignore

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Annotate with a concrete event class: async def on_event(self, message: MyEvent, ctx: MessageContext) -> None
2. Make sure the annotated class is importable at runtime (no TYPE_CHECKING-only string refs)
3. For multiple events, use a union of concrete classes: message: EventA | EventB

Example fix

# before
@event
async def on_event(self, message, ctx: MessageContext) -> None: ...

# after
@event
async def on_event(self, message: MyEvent, ctx: MessageContext) -> None: ...

from typing import get_type_hints

def message_hint_resolves(func) -> bool:
    hints = get_type_hints(func)
    return isinstance(hints.get("message"), type)

def has_concrete_message_type(func) -> bool:
    return isinstance(get_type_hints(func).get("message"), type)

When it happens

Trigger: async def on_event(self, message, ctx: MessageContext) -> None with no annotation; annotation is a bare TypeVar, unparameterized generic, or forward reference that get_type_hints cannot resolve at runtime.

Common situations: Quickly sketching an event handler without annotations; using TYPE_CHECKING-only imports referenced as strings; annotating with Any (which yields no routable target types).

Related errors

• Message type not found
• Return type not found
• 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/634118fc2303aed4. Report an issue: GitHub.