microsoft/semantic-kernel · error · AssertionError

Return type not found. Please use `None` as the type hint of

Error message

Return type not found. Please use `None` as the type hint of the return type.

What it means

Raised at decoration time by the @event decorator. After confirming a 'return' annotation exists, it calls get_types() to extract concrete types. If the annotation is not interpretable as a class/Union/Optional/Any/NoneType (for example a typing special form like NoReturn/Never, a TypeVar, a parametrized generic alias such as list[int], or a Literal), get_types returns None and the decorator raises this AssertionError. Event handlers must return None, so the return annotation must be -> None.

Source

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

    def decorator(
        func: Callable[[AgentT, ReceivesT, MessageContext], Coroutine[Any, Any, None]],
    ) -> MessageHandler[AgentT, ReceivesT, None]:
        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. Please provide a type hint for the message parameter.")

        return_types = get_types(type_hints["return"])

        if return_types is None:
            raise AssertionError("Return type not found. Please use `None` as the type hint of the return type.")

        # Convert target_types to list and stash

        @wraps(func)
        async def wrapper(self: AgentT, message: ReceivesT, ctx: MessageContext) -> None:
            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)  # type: ignore

            if return_value is not None:
                if strict:
                    raise ValueError(f"Return type {type(return_value)} is not None.")
                logger.warning(f"Return type {type(return_value)} is not None. It will be ignored.")

            return

View on GitHub (pinned to c028a0c7dc)

Solutions

Annotate the handler return as -> None.
If the handler must return a value, use the @rpc decorator instead of @event.
Avoid TypeVar, Literal, parametrized generic aliases, and NoReturn/Never as return annotations on event handlers.

Example fix

// before
@event
async def on_event(self, msg: MyEvent, ctx: MessageContext) -> NoReturn:
    ...

// after
@event
async def on_event(self, msg: MyEvent, ctx: MessageContext) -> None:
    ...

Defensive patterns

Strategy: validation

Validate before calling

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

def event_return_ok(fn) -> bool:
    hints = get_type_hints(fn)
    if 'return' not in hints:
        return False
    return get_types(hints['return']) is not None

Type guard

from types import NoneType

def returns_none(fn) -> bool:
    from typing import get_type_hints
    hints = get_type_hints(fn)
    return hints.get('return') in (NoneType, type(None))

Prevention

Always annotate @event handlers with -> None.
Assert get_type_hints(handler)['return'] resolves in unit tests for every handler.
Run mypy/pyright with disallow_untyped_defs to force complete annotations.

When it happens

Trigger: Decorating a method with @event whose return annotation is present but not a resolvable concrete type, e.g. -> NoReturn, -> T (a TypeVar), -> list[int], -> Literal['x'], or -> NewType. Annotating with -> None (resolved to NoneType) does NOT trigger this.

Common situations: Copying a handler from an RPC sample and leaving an exotic return hint; using a TypeVar/NewType as the return annotation; refactoring without fixing the return hint.

Related errors

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