{"record":{"id":"d6d8faf5b3cbba00","repo":"microsoft/semantic-kernel","slug":"message-type-not-found-please-provide-a-type-hint","errorCode":null,"errorMessage":"Message type not found. Please provide a type hint for the message parameter.","messagePattern":"Message type not found\\. Please provide a type hint for the message parameter\\.","errorType":"exception","errorClass":"AssertionError","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/runtime/core/routed_agent.py","lineNumber":271,"sourceCode":"            is applied in alphabetical order of the handlers and the first matching handler will be called while the\n            rest are skipped. If `None`, the first handler in alphabetical order matching the same message type will be\n            called.\n    \"\"\"\n\n    def decorator(\n        func: Callable[[AgentT, ReceivesT, MessageContext], Coroutine[Any, Any, None]],\n    ) -> MessageHandler[AgentT, ReceivesT, None]:\n        type_hints = get_type_hints(func)\n        if \"message\" not in type_hints:\n            raise AssertionError(\"message parameter not found in function signature\")\n\n        if \"return\" not in type_hints:\n            raise AssertionError(\"return not found in function signature\")\n\n        # Get the type of the message parameter\n        target_types = get_types(type_hints[\"message\"])\n        if target_types is None:\n            raise AssertionError(\"Message type not found. Please provide a type hint for the message parameter.\")\n\n        return_types = get_types(type_hints[\"return\"])\n\n        if return_types is None:\n            raise AssertionError(\"Return type not found. Please use `None` as the type hint of the return type.\")\n\n        # Convert target_types to list and stash\n\n        @wraps(func)\n        async def wrapper(self: AgentT, message: ReceivesT, ctx: MessageContext) -> None:\n            if type(message) not in target_types:\n                if strict:\n                    raise CantHandleException(f\"Message type {type(message)} not in target types {target_types}\")\n                logger.warning(f\"Message type {type(message)} not in target types {target_types}\")\n\n            return_value = await func(self, message, ctx)  # type: ignore\n\n            if return_value is not None:","sourceCodeStart":253,"sourceCodeEnd":289,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/runtime/core/routed_agent.py#L253-L289","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Annotate message with a concrete event class, a Union of classes, Optional[...], or Any.","Import the event class at runtime so get_type_hints can resolve it.","Replace TypeVar/forward-ref annotations with the actual event class.","Reproduce with get_type_hints(method) to see what fails to resolve."],"exampleFix":"// before\nE = TypeVar(\"E\")\n@event\nasync def on_event(self, message: E, ctx: MessageContext) -> None: ...\n// after\n@event\nasync def on_event(self, message: MyEvent, ctx: MessageContext) -> None: ...","handlingStrategy":"validation","validationCode":"from typing import get_type_hints\nfrom semantic_kernel.agents.runtime.core.type_helpers import get_types\n\ndef event_message_type_resolves(func) -> bool:\n    hints = get_type_hints(func)\n    return \"message\" in hints and get_types(hints[\"message\"]) is not None","typeGuard":"from typing import get_type_hints, Callable\nfrom semantic_kernel.agents.runtime.core.type_helpers import get_types\n\ndef has_resolvable_event_message_type(func: Callable) -> bool:\n    try:\n        hints = get_type_hints(func)\n        return get_types(hints.get(\"message\")) is not None\n    except Exception:\n        return False","tryCatchPattern":null,"preventionTips":["Annotate event message with concrete classes, Union, Optional, or Any.","Import event classes at runtime, not only under TYPE_CHECKING.","Avoid bare TypeVars for the event message type.","Run get_type_hints in unit tests to catch resolution failures."],"tags":["runtime","decorators","event-handler","type-hints","semantic-kernel"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}