{"record":{"id":"4e78be69fa5286c8","repo":"microsoft/semantic-kernel","slug":"return-type-not-found","errorCode":null,"errorMessage":"Return type not found","messagePattern":"Return type not found","errorType":"exception","errorClass":"AssertionError","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/runtime/core/routed_agent.py","lineNumber":145,"sourceCode":"    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:\n                if strict:\n                    raise ValueError(f\"Return type {type(return_value)} not in return types {return_types}\")\n                logger.warning(f\"Return type {type(return_value)} not in return types {return_types}\")\n\n            return return_value","sourceCodeStart":127,"sourceCodeEnd":163,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/runtime/core/routed_agent.py#L127-L163","documentation":"Raised by the @message_handler decorator when the return annotation cannot be resolved into concrete types by get_types. The handler must declare what it produces so the runtime can route replies; an unresolvable return type (bare TypeVar, unresolvable forward ref, ParamSpec) blocks this.","triggerScenarios":"Annotating the return as an unbound TypeVar, a special typing form other than Any/None/Union/Optional, or a string forward reference that get_type_hints fails to evaluate.","commonSituations":"Reusing a generic TypeVar for the return type; lazy imports of the response message class; from __future__ import annotations with a typo'd return type.","solutions":["Annotate the return with a concrete class, Union of classes, Optional[...], None, or Any.","Import the response message class at runtime so get_type_hints can resolve it.","Replace TypeVar returns with the concrete response type.","For no response, annotate -> None."],"exampleFix":"// before\nR = TypeVar(\"R\")\n@message_handler\nasync def handle(self, message: MyMsg, ctx: MessageContext) -> R: ...\n// after\n@message_handler\nasync def handle(self, message: MyMsg, ctx: MessageContext) -> MyResponse: ...","handlingStrategy":"validation","validationCode":"from typing import get_type_hints\nfrom semantic_kernel.agents.runtime.core.type_helpers import get_types\n\ndef return_type_resolves(func) -> bool:\n    hints = get_type_hints(func)\n    return \"return\" in hints and get_types(hints[\"return\"]) 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_return_type(func: Callable) -> bool:\n    try:\n        hints = get_type_hints(func)\n        return get_types(hints.get(\"return\")) is not None\n    except Exception:\n        return False","tryCatchPattern":null,"preventionTips":["Annotate returns with concrete classes, Union, Optional, None, or Any.","Import response classes at runtime.","Avoid bare TypeVars for return types.","Validate with get_type_hints in tests."],"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"}