{"record":{"id":"262703155d79f32a","repo":"microsoft/autogen","slug":"failed-to-unpack-payload-into-self-cls","errorCode":null,"errorMessage":"Failed to unpack payload into {self.cls}","messagePattern":"Failed to unpack payload into (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/packages/autogen-core/src/autogen_core/_serialization.py","lineNumber":177,"sourceCode":"        self.cls = cls\n\n    @property\n    def data_content_type(self) -> str:\n        return PROTOBUF_DATA_CONTENT_TYPE\n\n    @property\n    def type_name(self) -> str:\n        return _type_name(self.cls)\n\n    def deserialize(self, payload: bytes) -> ProtobufT:\n        # Parse payload into a proto any\n        any_proto = any_pb2.Any()\n        any_proto.ParseFromString(payload)\n\n        destination_message = self.cls()\n\n        if not any_proto.Unpack(destination_message):  # type: ignore\n            raise ValueError(f\"Failed to unpack payload into {self.cls}\")\n\n        return destination_message\n\n    def serialize(self, message: ProtobufT) -> bytes:\n        any_proto = any_pb2.Any()\n        any_proto.Pack(message)  # type: ignore\n        return any_proto.SerializeToString()\n\n\n@dataclass\nclass UnknownPayload:\n    type_name: str\n    data_content_type: str\n    payload: bytes\n\n\ndef _type_name(cls: type[Any] | Any) -> str:\n    # If cls is a protobuf, then we need to determine the descriptor","sourceCodeStart":159,"sourceCodeEnd":195,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-core/src/autogen_core/_serialization.py#L159-L195","documentation":"ProtobufMessageSerializer.deserialize wraps payloads in google.protobuf.Any; Unpack fails (returns False) when the embedded message's concrete type does not match the registered self.cls. The code then raises ValueError, meaning the bytes were valid Any-encoded data but not the protobuf message type this serializer expects.","triggerScenarios":"A message arrives on a serializer registered for MessageTypeA but the payload contains MessageTypeB packed in Any; two agents use different .proto definitions for the same type_name; the payload is corrupted or not Any-wrapped at all (e.g. raw JSON sent to a protobuf serializer, or content-type mismatch on the wire).","commonSituations":"Schema drift between publisher and subscriber protobuf definitions; reusing a type_name across different message classes; cross-runtime (grpc worker) setups where one side was not rebuilt after a .proto change; serializing with serialize() but deserializing with a serializer constructed for a different generated class.","solutions":["Verify both ends register ProtobufMessageSerializer for the exact same generated protobuf class","Check any_proto.Is(destination_message) before unpacking, or catch ValueError and log payload diagnostic info (type_url)","Ensure the type_name used in registration is unique per message class so payloads are routed to the right serializer","Regenerate Python protobuf stubs on all processes after editing .proto files"],"exampleFix":"# before\nmsg = serializer.deserialize(payload)  # ValueError if wrong type\n\n# after\nfrom google.protobuf import any_pb2\nany_proto = any_pb2.Any()\nany_proto.ParseFromString(payload)\nif not any_proto.Is(MessageTypeA()):\n    raise TypeError(f\"got {any_proto.type_url}, expected {MessageTypeA.DESCRIPTOR.full_name}\")\nmsg = serializer.deserialize(payload)","handlingStrategy":"try-catch","validationCode":"from google.protobuf import any_pb2\n\ndef payload_matches(payload: bytes, cls) -> bool:\n    a = any_pb2.Any()\n    if not a.ParseFromString(payload):\n        return False\n    return a.Is(cls())","typeGuard":"def is_registered_proto(serializer, cls) -> bool:\n    return serializer.cls is cls","tryCatchPattern":"try:\n    msg = serializer.deserialize(payload)\nexcept ValueError as e:\n    if \"Failed to unpack\" in str(e):\n        a = any_pb2.Any(); a.ParseFromString(payload)\n        raise TypeError(f\"payload was {a.type_url}, expected {serializer.cls.DESCRIPTOR.full_name}\") from e\n    raise","preventionTips":["Register each protobuf class under a unique type_name","Regenerate stubs on all services together after .proto changes","Log any_proto.type_url on failed unpacks to pinpoint schema drift"],"tags":["autogen-core","serialization","protobuf","schema-mismatch"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}