{"record":{"id":"bec327f1a6287f3d","repo":"microsoft/autogen","slug":"no-serializers-found-for-type-type-please-provi","errorCode":null,"errorMessage":"No serializers found for type {type}. Please provide an explicit serializer.","messagePattern":"No serializers found for type (.+?)\\. Please provide an explicit serializer\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/packages/autogen-core/src/autogen_core/_base_agent.py","lineNumber":52,"sourceCode":"\n    def decorator(cls: Type[BaseAgentType]) -> Type[BaseAgentType]:\n        cls.internal_unbound_subscriptions_list.append(subscription)\n        return cls\n\n    return decorator\n\n\ndef handles(\n    type: Type[Any], serializer: MessageSerializer[Any] | List[MessageSerializer[Any]] | None = None\n) -> Callable[[Type[BaseAgentType]], Type[BaseAgentType]]:\n    def decorator(cls: Type[BaseAgentType]) -> Type[BaseAgentType]:\n        if serializer is None:\n            serializer_list = try_get_known_serializers_for_type(type)\n        else:\n            serializer_list = [serializer] if not isinstance(serializer, Sequence) else serializer\n\n        if len(serializer_list) == 0:\n            raise ValueError(f\"No serializers found for type {type}. Please provide an explicit serializer.\")\n\n        cls.internal_extra_handles_types.append((type, serializer_list))\n        return cls\n\n    return decorator\n\n\nclass BaseAgent(ABC, Agent):\n    internal_unbound_subscriptions_list: ClassVar[List[UnboundSubscription]] = []\n    \"\"\":meta private:\"\"\"\n    internal_extra_handles_types: ClassVar[List[Tuple[Type[Any], List[MessageSerializer[Any]]]]] = []\n    \"\"\":meta private:\"\"\"\n\n    def __init_subclass__(cls, **kwargs: Any) -> None:\n        super().__init_subclass__(**kwargs)\n        # Automatically set class_variable in each subclass so that they are not shared between subclasses\n        cls.internal_extra_handles_types = []\n        cls.internal_unbound_subscriptions_list = []","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-core/src/autogen_core/_base_agent.py#L34-L70","documentation":"The @handles(type) decorator on an agent class resolves serializers for the decorated message type via try_get_known_serializers_for_type(type). That lookup only finds serializers for types known to the runtime's serialization registry (dataclasses and pydantic models by default). If nothing is registered/known for the type and no explicit serializer was passed, it raises ValueError.","triggerScenarios":"@handles(SomeType) where SomeType is a plain class, TypedDict, NamedTuple, or a dataclass/pydantic model whose serializer was removed or is unimportable; using @handles on types from modules not imported so the registry lookup fails.","commonSituations":"Declaring message protocols with non-dataclass types; third-party message types without autogen serializers; upgrading autogen versions where serializer registration behavior changed; passing a serializer list that is empty.","solutions":["Pass an explicit serializer: @handles(MyMsg, serializer=MyMsgSerializer()) where MyMsgSerializer implements MessageSerializer[MyMsg].","Make the message type a @dataclass or pydantic BaseModel so try_get_known_serializers_for_type can build serializers automatically.","If importing the message type from another package, verify that package's serializers import cleanly (no ImportError swallowed during registration).","Check for typos — decorating a different type than the one you serialize."],"exampleFix":"# before\nclass MyMsg:  # plain class: no serializer discoverable\n    ...\n\n@handles(MyMsg)\nclass MyAgent(RoutedAgent): ...\n\n# after\nfrom dataclasses import dataclass\n\n@dataclass\nclass MyMsg:\n    content: str\n\n@handles(MyMsg)\nclass MyAgent(RoutedAgent): ...","handlingStrategy":"validation","validationCode":"from autogen_core import try_get_known_serializers_for_type\n\n# before applying @handles(Msg)\nserializers = try_get_known_serializers_for_type(Msg)\nif not serializers:\n    # make Msg a dataclass/pydantic model, or prepare an explicit MessageSerializer\n    serializers = [MyMsgSerializer()]","typeGuard":"from dataclasses import is_dataclass\nfrom pydantic import BaseModel\n\ndef has_autogen_serializer(t: type) -> bool:\n    return is_dataclass(t) or (isinstance(t, type) and issubclass(t, BaseModel))","tryCatchPattern":null,"preventionTips":["Model messages as @dataclass or pydantic BaseModel by default.","For exotic types, write a MessageSerializer and pass it explicitly: @handles(Msg, serializer=MsgSerializer()).","Import message modules before decorating so serializer registration is visible."],"tags":["autogen-core","serialization","decorator","message-types"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}