{"record":{"id":"9d952cdb6a7c9b4f","repo":"microsoft/semantic-kernel","slug":"message-type-type-message-not-in-target-types","errorCode":null,"errorMessage":"Message type {type(message)} not in target types {target_types}","messagePattern":"Message type (.+?) not in target types (.+?)","errorType":"exception","errorClass":"CantHandleException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/runtime/core/routed_agent.py","lineNumber":153,"sourceCode":"            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\n\n        wrapper_handler = cast(MessageHandler[AgentT, ReceivesT, ProducesT], wrapper)\n        wrapper_handler.target_types = list(target_types)\n        wrapper_handler.produces_types = list(return_types)\n        wrapper_handler.is_message_handler = True\n        wrapper_handler.router = match or (lambda _message, _ctx: True)\n\n        return wrapper_handler","sourceCodeStart":135,"sourceCodeEnd":171,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/runtime/core/routed_agent.py#L135-L171","documentation":"Raised at runtime by the @message_handler wrapper (strict mode) when an incoming message's concrete type is not in the handler's declared target_types. This is a routing/contract mismatch: the runtime dispatched a message to a handler whose signature does not cover that type.","triggerScenarios":"The runtime delivers a message of type X to a handler declared for type Y (or a Union not including X), and strict=True (default for the wrapper). Happens with shared topics, mismatched subscriptions, or when a subclass changes the message type but not the subscription.","commonSituations":"Two handlers on the same topic with overlapping but not identical message types; publishing a message type the handler was not declared to receive; inheritance where a base handler is reused for a new message type without updating the annotation.","solutions":["Add the delivered message type to the handler's message annotation (Union[Existing, NewType]).","Set strict=False to demote this to a logged warning (only if skipping is acceptable).","Fix the subscription/routing so the message is delivered to a handler that declares it.","Ensure the published message is an instance of a declared type, not a subclass whose exact type() differs."],"exampleFix":"// before\n@message_handler\nasync def handle(self, message: Foo, ctx: MessageContext) -> None: ...\n# runtime delivers Bar -> CantHandleException\n// after\n@message_handler\nasync def handle(self, message: Union[Foo, Bar], ctx: MessageContext) -> None: ...","handlingStrategy":"try-catch","validationCode":"from semantic_kernel.agents.runtime.core.type_helpers import get_types\n\ndef message_in_target_types(message, target_types) -> bool:\n    return type(message) in target_types","typeGuard":"from typing import Any\n\ndef message_matches_handler(message: Any, target_types) -> bool:\n    return type(message) in target_types","tryCatchPattern":"from semantic_kernel.agents.runtime.core.exceptions import CantHandleException\n\ntry:\n    await handler.run(message, ctx)\nexcept CantHandleException as e:\n    if \"not in target types\" in str(e):\n        # route to the correct handler or set strict=False\n        pass\n    else:\n        raise","preventionTips":["Declare all deliverable message types in the handler's Union annotation.","Set strict=False when skipping unmatched messages is acceptable.","Verify the published message is an instance of a declared type (exact type matters).","Audit subscriptions so messages route to handlers that declare them."],"tags":["runtime","message-handler","routing","semantic-kernel"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}