microsoft/semantic-kernel · error · AssertionError

Return type not found

Error message

Return type not found

What it means

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.

Source

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

    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:
            if type(message) not in target_types:
                if strict:
                    raise CantHandleException(f"Message type {type(message)} not in target types {target_types}")
                logger.warning(f"Message type {type(message)} not in target types {target_types}")

            return_value = await func(self, message, ctx)

            if AnyType not in return_types and type(return_value) not in return_types:
                if strict:
                    raise ValueError(f"Return type {type(return_value)} not in return types {return_types}")
                logger.warning(f"Return type {type(return_value)} not in return types {return_types}")

            return return_value

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Annotate the return with a concrete class, Union of classes, Optional[...], None, or Any.
2. Import the response message class at runtime so get_type_hints can resolve it.
3. Replace TypeVar returns with the concrete response type.
4. For no response, annotate -> None.

Example fix

// before
R = TypeVar("R")
@message_handler
async def handle(self, message: MyMsg, ctx: MessageContext) -> R: ...
// after
@message_handler
async def handle(self, message: MyMsg, ctx: MessageContext) -> MyResponse: ...

from typing import get_type_hints
from semantic_kernel.agents.runtime.core.type_helpers import get_types

def return_type_resolves(func) -> bool:
    hints = get_type_hints(func)
    return "return" in hints and get_types(hints["return"]) is not None

from typing import get_type_hints, Callable
from semantic_kernel.agents.runtime.core.type_helpers import get_types

def has_resolvable_return_type(func: Callable) -> bool:
    try:
        hints = get_type_hints(func)
        return get_types(hints.get("return")) is not None
    except Exception:
        return False

When it happens

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

Common situations: 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.

Related errors

• Message type not found
• message parameter not found in function signature
• return not found in function signature
• Invalid arguments
• Message type not found. Please provide a type hint for the m

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