microsoft/semantic-kernel · error · ValueError

Failed to unpack payload into {self.cls}

Error message

Failed to unpack payload into {self.cls}

What it means

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.

Source

Thrown at python/semantic_kernel/agents/runtime/core/serialization.py:225

    def data_content_type(self) -> str:
        """Return the data content type."""
        return PROTOBUF_DATA_CONTENT_TYPE

    @property
    def type_name(self) -> str:
        """Return the type name."""
        return _type_name(self.cls)

    def deserialize(self, payload: bytes) -> ProtobufT:
        """Deserialize the payload into a Protobuf message."""
        # Parse payload into a proto any
        any_proto = any_pb2.Any()
        any_proto.ParseFromString(payload)

        destination_message = self.cls()

        if not any_proto.Unpack(destination_message):  # type: ignore
            raise ValueError(f"Failed to unpack payload into {self.cls}")

        return destination_message

    def serialize(self, message: ProtobufT) -> bytes:
        """Serialize the Protobuf message into a payload."""
        any_proto = any_pb2.Any()
        any_proto.Pack(message)  # type: ignore
        return any_proto.SerializeToString()


@experimental
@dataclass
class UnknownPayload:
    """Class to represent an unknown payload."""

    type_name: str
    data_content_type: str
    payload: bytes

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Ensure the sender serializes with the same protobuf type the receiver deserializes.
2. Verify the Any type_url matches the destination message's DESCRIPTOR.full_name before unpacking.
3. Validate integrity / length of the payload before deserializing.
4. Keep protobuf definitions in sync across services.

from google.protobuf import any_pb2

def type_url_matches(payload: bytes, cls) -> bool:
    a = any_pb2.Any()
    a.ParseFromString(payload)
    expected = f"type.googleapis.com/{cls.DESCRIPTOR.full_name}"
    return a.type_url == expected

try:
    msg = serializer.deserialize(payload)
except ValueError as e:
    logger.error('Protobuf unpack failed (type mismatch/corruption): %s', e)

When it happens

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

Common situations: Cross-type deserialization; sending one protobuf message and decoding as another; transport corruption; schema drift after a protobuf change.

Related errors

• Unable to restore channel: invalid state.
• The option key '{key}' value must be of type '{typeof(T)}' b
• Unable to transform output to {typeof(TOutput)}.
• Unable to transform result into {typeof(TOutput).Name}
• The provided audio options '{executionSettings.Audio?.GetTyp

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/5b0e37e27ffe0cc9. Report an issue: GitHub.