{"record":{"id":"825726b9f09ac3cb","repo":"microsoft/semantic-kernel","slug":"message-type-not-found","errorCode":null,"errorMessage":"Message type not found","messagePattern":"Message type not found","errorType":"exception","errorClass":"AssertionError","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/runtime/core/routed_agent.py","lineNumber":140,"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\n            be called.\n    \"\"\"\n\n    def decorator(\n        func: Callable[[AgentT, ReceivesT, MessageContext], Coroutine[Any, Any, ProducesT]],\n    ) -> MessageHandler[AgentT, ReceivesT, ProducesT]:\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\")\n\n        return_types = get_types(type_hints[\"return\"])\n\n        if return_types is None:\n            raise AssertionError(\"Return type not found\")\n\n        # Convert target_types to list and stash\n\n        @wraps(func)\n        async def wrapper(self: AgentT, message: ReceivesT, ctx: MessageContext) -> ProducesT:\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)\n\n            if AnyType not in return_types and type(return_value) not in return_types:","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/runtime/core/routed_agent.py#L122-L158","documentation":"Raised by the @message_handler decorator when the 'message' parameter has a type hint that get_types cannot resolve into concrete types. get_types returns None for typing special forms (e.g. a bare TypeVar, a ParamSpec, or a forward reference that cannot be evaluated), so the handler cannot be routed by message type.","triggerScenarios":"Annotating message as an unbound TypeVar, a string forward reference that get_type_hints cannot resolve, Any (returns AnyType, fine) vs an unresolvable special form, or a ParamSpec/Concatenate construct.","commonSituations":"Using a generic TypeVar for the message type; referencing a message class that is imported lazily or only under TYPE_CHECKING; typos in the type name with from __future__ import annotations.","solutions":["Annotate message with a concrete class, a Union of classes, Optional[...], or Any.","Ensure the referenced message class is imported at runtime (not only under TYPE_CHECKING).","Replace TypeVar/forward-ref annotations with the actual message class.","Run get_type_hints on the method manually to reproduce the resolution failure."],"exampleFix":"// before\nT = TypeVar(\"T\")\n@message_handler\nasync def handle(self, message: T, ctx: MessageContext) -> None: ...\n// after\n@message_handler\nasync def handle(self, message: MyMsg, 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 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_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 message with concrete classes, Union, Optional, or Any.","Import message classes at runtime, not only under TYPE_CHECKING.","Avoid bare TypeVars or ParamSpec for message types.","Run get_type_hints in unit tests to catch resolution failures."],"tags":["runtime","decorators","message-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"}