microsoft/semantic-kernel · error · AssertionError

message parameter not found in function signature

Error message

message parameter not found in function signature

What it means

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.

Source

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

    than one message type by returning a Union of the message types.

    Args:
        func: The function to be decorated.
        strict: If `True`, the handler will raise an exception if the message type or return type is not in the target
            types. If `False`, it will log a warning instead.
        match: A function that takes the message and the context as arguments and returns a boolean. This is used for
            secondary routing after the message type. For handlers addressing the same message type, the match function
            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, ProducesT]],
    ) -> MessageHandler[AgentT, ReceivesT, ProducesT]:
        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")

        return_types = get_types(type_hints["return"])

        if return_types is None:
            raise AssertionError("Return type not found")

        # Convert target_types to list and stash

        @wraps(func)
        async def wrapper(self: AgentT, message: ReceivesT, ctx: MessageContext) -> ProducesT:

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Name the second parameter exactly 'message' and give it a type hint.
2. Ensure the method signature is async def handler(self, message: MyMsg, ctx: MessageContext) -> ....
3. Avoid *args/**kwargs in handler signatures.
4. Re-import after fixing the signature (error is raised at import/class-definition time).

Example fix

// before
@message_handler
async def handle(self, msg: MyMsg, ctx: MessageContext) -> None: ...
// after
@message_handler
async def handle(self, message: MyMsg, ctx: MessageContext) -> None: ...

from typing import get_type_hints

def handler_has_message_param(func) -> bool:
    return "message" in get_type_hints(func)

from typing import get_type_hints, Callable

def is_valid_handler_signature(func: Callable) -> bool:
    try:
        hints = get_type_hints(func)
    except Exception:
        return False
    return "message" in hints and "return" in hints

When it happens

Trigger: 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.

Common situations: Renaming the parameter for readability; copy-pasting a handler and renaming args; using @message_handler on a method with the wrong signature.

Related errors

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

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