{"record":{"id":"1c23c268fd08cc36","repo":"microsoft/semantic-kernel","slug":"message-parameter-not-found-in-function-signature","errorCode":null,"errorMessage":"message parameter not found in function signature","messagePattern":"message parameter not found in function signature","errorType":"exception","errorClass":"AssertionError","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/runtime/core/routed_agent.py","lineNumber":132,"sourceCode":"    than one message type by returning a Union of the message types.\n\n    Args:\n        func: The function to be decorated.\n        strict: If `True`, the handler will raise an exception if the message type or return type is not in the target\n            types. If `False`, it will log a warning instead.\n        match: A function that takes the message and the context as arguments and returns a boolean. This is used for\n            secondary routing after the message type. For handlers addressing the same message type, the match function\n            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:","sourceCodeStart":114,"sourceCodeEnd":150,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/runtime/core/routed_agent.py#L114-L150","documentation":"Raised by the @message_handler decorator (RPC handler) at class-definition time when the decorated method's type hints do not include a parameter named 'message'. The decorator uses get_type_hints to discover the message type for routing, so a missing or differently-named parameter cannot be wired.","triggerScenarios":"Decorating a method whose second positional parameter is not named 'message' (e.g. 'msg', 'payload'), or using *args/**kwargs so 'message' is absent from the resolved hints.","commonSituations":"Renaming the parameter for readability; copy-pasting a handler and renaming args; using @message_handler on a method with the wrong signature.","solutions":["Name the second parameter exactly 'message' and give it a type hint.","Ensure the method signature is async def handler(self, message: MyMsg, ctx: MessageContext) -> ....","Avoid *args/**kwargs in handler signatures.","Re-import after fixing the signature (error is raised at import/class-definition time)."],"exampleFix":"// before\n@message_handler\nasync def handle(self, msg: MyMsg, 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\n\ndef handler_has_message_param(func) -> bool:\n    return \"message\" in get_type_hints(func)","typeGuard":"from typing import get_type_hints, Callable\n\ndef is_valid_handler_signature(func: Callable) -> bool:\n    try:\n        hints = get_type_hints(func)\n    except Exception:\n        return False\n    return \"message\" in hints and \"return\" in hints","tryCatchPattern":null,"preventionTips":["Always name the second handler parameter 'message'.","Add a type hint to the message parameter.","Avoid *args/**kwargs in handler signatures.","Fix at class-definition time; errors surface on import."],"tags":["runtime","decorators","message-handler","semantic-kernel"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}