microsoft/autogen · error · ValueError

Unknown metadata type: {type(metadata)}

Error message

Unknown metadata type: {type(metadata)}

What it means

In the telemetry propagation helper, get_telemetry_context_from_metadata accepts only three shapes: None (empty context), an EnvelopeMetadata instance, or any object exposing __getitem__ (dict-like remote-call metadata such as gRPC/OPC metadata). Anything else raises ValueError with the offending type name. The function is part of OpenTelemetry trace-context propagation, so the error means your metadata carrier is an unsupported type before telemetry extraction can even run.

Source

Thrown at python/packages/autogen-core/src/autogen_core/_telemetry/_propagation.py:99

def get_telemetry_context(metadata: TelemetryMetadataContainer) -> Context:
    """
    Retrieves the telemetry context from the given metadata.

    Args:
        metadata (Optional[EnvelopeMetadata]): The metadata containing the telemetry context.

    Returns:
        Context: The telemetry context extracted from the metadata, or an empty context if the metadata is None.
    """
    if metadata is None:
        return Context()
    elif isinstance(metadata, EnvelopeMetadata):
        return extract(_get_carrier_for_envelope_metadata(metadata))
    elif hasattr(metadata, "__getitem__"):
        return extract(_get_carrier_for_remote_call_metadata(metadata))
    else:
        raise ValueError(f"Unknown metadata type: {type(metadata)}")


def get_telemetry_links(
    metadata: TelemetryMetadataContainer,
) -> Optional[Sequence[Link]]:
    """
    Retrieves the telemetry links from the given metadata.

    Args:
        metadata (Optional[EnvelopeMetadata]): The metadata containing the telemetry links.

    Returns:
        Optional[Sequence[Link]]: The telemetry links extracted from the metadata, or None if there are no links.
    """
    if metadata is None:
        return None
    elif isinstance(metadata, EnvelopeMetadata):
        context = extract(_get_carrier_for_envelope_metadata(metadata))

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Convert your metadata to a dict (or any Mapping) before it reaches the runtime — duck-typed __getitem__ support is enough.
2. Use autogen_core's own EnvelopeMetadata when attaching telemetry context to message envelopes.
3. Pass None when there is no telemetry context to propagate.
4. If you wrote a custom transport, mirror how the built-in gRPC transport exposes metadata as a Mapping.

Example fix

# before
span_context = get_telemetry_context_from_metadata("traceparent: 00-abc...")  # ValueError

# after
span_context = get_telemetry_context_from_metadata({"traceparent": "00-abc..."})

def is_supported_metadata(md: object) -> bool:
    return md is None or isinstance(md, EnvelopeMetadata) or hasattr(md, "__getitem__")

assert is_supported_metadata(my_metadata)

from typing import Mapping, Optional, Union
from autogen_core.models._types import EnvelopeMetadata  # adjust import to actual path

SupportedMetadata = Optional[Union[EnvelopeMetadata, Mapping[str, str]]]

try:
    ctx = get_telemetry_context_from_metadata(md)
except ValueError:
    ctx = Context()  # telemetry is best-effort; degrade to no propagation

When it happens

Trigger: Passing a string, bytes, list of tuples without __getitem__, a dataclass, or a custom metadata object to the telemetry extraction path — typically indirectly by putting a non-standard metadata object on a message envelope or RPC call that the runtime then instruments.

Common situations: Custom transports or protocols that define their own metadata type instead of reusing EnvelopeMetadata or a Mapping; upgrading autogen-core where the telemetry module became stricter; test doubles that stub metadata with a plain object() or NamedTuple.

Related errors

• Unknown destination type: {type(destination)}
• Invalid topic type: {self.type}. Must match the pattern: ^[\
• Invalid topic id: {topic_id}
• The string must contain exactly one function
• buffer_size must be greater than 0.

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