microsoft/semantic-kernel · 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

Raised by the @event decorator when the 'message' parameter's type hint cannot be resolved into concrete types by get_types. Event routing requires a known message type; a bare TypeVar, an unresolvable forward reference, or a typing special form yields None and the event cannot be subscribed.

Source

Thrown at python/semantic_kernel/agents/runtime/core/routed_agent.py:271

            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 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}")
                logger.warning(f"Message type {type(message)} not in target types {target_types}")

            return_value = await func(self, message, ctx)  # type: ignore

            if return_value is not None:

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Annotate message with a concrete event class, a Union of classes, Optional[...], or Any.
2. Import the event class at runtime so get_type_hints can resolve it.
3. Replace TypeVar/forward-ref annotations with the actual event class.
4. Reproduce with get_type_hints(method) to see what fails to resolve.

Example fix

// before
E = TypeVar("E")
@event
async def on_event(self, message: E, ctx: MessageContext) -> None: ...
// after
@event
async def on_event(self, message: MyEvent, ctx: MessageContext) -> None: ...

from typing import get_type_hints
from semantic_kernel.agents.runtime.core.type_helpers import get_types

def event_message_type_resolves(func) -> bool:
    hints = get_type_hints(func)
    return "message" in hints and get_types(hints["message"]) is not None

from typing import get_type_hints, Callable
from semantic_kernel.agents.runtime.core.type_helpers import get_types

def has_resolvable_event_message_type(func: Callable) -> bool:
    try:
        hints = get_type_hints(func)
        return get_types(hints.get("message")) is not None
    except Exception:
        return False

When it happens

Trigger: Annotating the event message as an unbound TypeVar, a string forward reference get_type_hints cannot evaluate, or a typing construct get_types does not handle (ParamSpec, Concatenate).

Common situations: Generic event handlers using a TypeVar for the message type; lazily-imported event classes referenced only under TYPE_CHECKING; typos in string annotations with from __future__ import annotations.

Related errors

• Message type not found
• Return type not found
• No serializers found for type {msg_type!r}. Please provide a
• message parameter not found in function signature
• return not found in function signature

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/d6d8faf5b3cbba00. Report an issue: GitHub.