{"record":{"id":"5b0e37e27ffe0cc9","repo":"microsoft/semantic-kernel","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":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/runtime/core/serialization.py","lineNumber":225,"sourceCode":"    def data_content_type(self) -> str:\n        \"\"\"Return the data content type.\"\"\"\n        return PROTOBUF_DATA_CONTENT_TYPE\n\n    @property\n    def type_name(self) -> str:\n        \"\"\"Return the type name.\"\"\"\n        return _type_name(self.cls)\n\n    def deserialize(self, payload: bytes) -> ProtobufT:\n        \"\"\"Deserialize the payload into a Protobuf message.\"\"\"\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        \"\"\"Serialize the Protobuf message into a payload.\"\"\"\n        any_proto = any_pb2.Any()\n        any_proto.Pack(message)  # type: ignore\n        return any_proto.SerializeToString()\n\n\n@experimental\n@dataclass\nclass UnknownPayload:\n    \"\"\"Class to represent an unknown payload.\"\"\"\n\n    type_name: str\n    data_content_type: str\n    payload: bytes","sourceCodeStart":207,"sourceCodeEnd":243,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/runtime/core/serialization.py#L207-L243","documentation":"Raised by ProtobufMessageSerializer.deserialize. It parses the payload as a protobuf Any, then calls any_proto.Unpack(destination_message). Unpack returns False when the Any's type_url does not match the destination message's full name (the payload was packed as a different protobuf type) or the bytes are malformed/truncated. On failure the serializer raises ValueError.","triggerScenarios":"Deserializing bytes that were serialized from a different protobuf type than self.cls; corrupt or truncated bytes; protobuf descriptor version skew between sender and receiver.","commonSituations":"Cross-type deserialization; sending one protobuf message and decoding as another; transport corruption; schema drift after a protobuf change.","solutions":["Ensure the sender serializes with the same protobuf type the receiver deserializes.","Verify the Any type_url matches the destination message's DESCRIPTOR.full_name before unpacking.","Validate integrity / length of the payload before deserializing.","Keep protobuf definitions in sync across services."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"from google.protobuf import any_pb2\n\ndef type_url_matches(payload: bytes, cls) -> bool:\n    a = any_pb2.Any()\n    a.ParseFromString(payload)\n    expected = f\"type.googleapis.com/{cls.DESCRIPTOR.full_name}\"\n    return a.type_url == expected","typeGuard":null,"tryCatchPattern":"try:\n    msg = serializer.deserialize(payload)\nexcept ValueError as e:\n    logger.error('Protobuf unpack failed (type mismatch/corruption): %s', e)","preventionTips":["Serialize and deserialize with the same protobuf type.","Validate the Any.type_url against the destination DESCRIPTOR.full_name before unpacking.","Keep .proto schemas version-aligned across services."],"tags":["serialization","protobuf","payload","type-mismatch"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}