microsoft/autogen · error · ValueError

No serializers found for type {type}. Please provide an expl

Error message

No serializers found for type {type}. Please provide an explicit serializer.

What it means

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.

Source

Thrown at python/packages/autogen-core/src/autogen_core/_base_agent.py:52

    def decorator(cls: Type[BaseAgentType]) -> Type[BaseAgentType]:
        cls.internal_unbound_subscriptions_list.append(subscription)
        return cls

    return decorator


def handles(
    type: Type[Any], serializer: MessageSerializer[Any] | List[MessageSerializer[Any]] | None = None
) -> Callable[[Type[BaseAgentType]], Type[BaseAgentType]]:
    def decorator(cls: Type[BaseAgentType]) -> Type[BaseAgentType]:
        if serializer is None:
            serializer_list = try_get_known_serializers_for_type(type)
        else:
            serializer_list = [serializer] if not isinstance(serializer, Sequence) else serializer

        if len(serializer_list) == 0:
            raise ValueError(f"No serializers found for type {type}. Please provide an explicit serializer.")

        cls.internal_extra_handles_types.append((type, serializer_list))
        return cls

    return decorator


class BaseAgent(ABC, Agent):
    internal_unbound_subscriptions_list: ClassVar[List[UnboundSubscription]] = []
    """:meta private:"""
    internal_extra_handles_types: ClassVar[List[Tuple[Type[Any], List[MessageSerializer[Any]]]]] = []
    """:meta private:"""

    def __init_subclass__(cls, **kwargs: Any) -> None:
        super().__init_subclass__(**kwargs)
        # Automatically set class_variable in each subclass so that they are not shared between subclasses
        cls.internal_extra_handles_types = []
        cls.internal_unbound_subscriptions_list = []

View on GitHub (pinned to 027ecf0a37)

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.

Example fix

# before
class MyMsg:  # plain class: no serializer discoverable
    ...

@handles(MyMsg)
class MyAgent(RoutedAgent): ...

# after
from dataclasses import dataclass

@dataclass
class MyMsg:
    content: str

@handles(MyMsg)
class MyAgent(RoutedAgent): ...

Defensive patterns

Strategy: validation

Validate before calling

from autogen_core import try_get_known_serializers_for_type

# before applying @handles(Msg)
serializers = try_get_known_serializers_for_type(Msg)
if not serializers:
    # make Msg a dataclass/pydantic model, or prepare an explicit MessageSerializer
    serializers = [MyMsgSerializer()]

Type guard

from dataclasses import is_dataclass
from pydantic import BaseModel

def has_autogen_serializer(t: type) -> bool:
    return is_dataclass(t) or (isinstance(t, type) and issubclass(t, BaseModel))

Prevention

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.

When it happens

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

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

Related errors

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/bec327f1a6287f3d. Report an issue: GitHub.