microsoft/autogen · warning · CantHandleException
TopicId does not match the subscription
Error message
TopicId does not match the subscription
What it means
TypeSubscription.map_to_agent() requires the topic type to equal the subscription's topic_type exactly (is_match is `topic_id.type == self._topic_type`). A mismatch raises CantHandleException, the same skip-signal used by the subscription manager when filtering subscriptions for a published topic. Unlike TypePrefixSubscription, no partial matching is done.
Source
Thrown at python/packages/autogen-core/src/autogen_core/_type_subscription.py:58
@property
def id(self) -> str:
return self._id
@property
def topic_type(self) -> str:
return self._topic_type
@property
def agent_type(self) -> str:
return self._agent_type
def is_match(self, topic_id: TopicId) -> bool:
return topic_id.type == self._topic_type
def map_to_agent(self, topic_id: TopicId) -> AgentId:
if not self.is_match(topic_id):
raise CantHandleException("TopicId does not match the subscription")
return AgentId(type=self._agent_type, key=topic_id.source)
def __eq__(self, other: object) -> bool:
if not isinstance(other, TypeSubscription):
return False
return self.id == other.id or (self.agent_type == other.agent_type and self.topic_type == other.topic_type)
View on GitHub (pinned to 027ecf0a37)
Solutions
- Gate with is_match() before mapping, or catch CantHandleException and skip.
- Make the subscription's topic_type exactly equal the published topic's type string.
- For hierarchical/prefixed topic types, switch to TypePrefixSubscription, whose is_match uses startswith.
Example fix
# before
sub = TypeSubscription(topic_type="events", agent_type="handler")
agent_id = sub.map_to_agent(TopicId("events.created", "src")) # CantHandleException
# after
from autogen_core._type_prefix_subscription import TypePrefixSubscription
sub = TypePrefixSubscription(topic_type_prefix="events", agent_type="handler")
agent_id = sub.map_to_agent(TopicId("events.created", "src")) # ok Defensive patterns
Strategy: type-guard
Validate before calling
if sub.is_match(topic_id): # exact string equality on topic type
agent_id = sub.map_to_agent(topic_id) Type guard
def can_map_type_sub(sub: TypeSubscription, topic_id: TopicId) -> bool:
return topic_id.type == sub.topic_type Try / catch
from autogen_core.exceptions import CantHandleException
try:
agent_id = sub.map_to_agent(topic_id)
except CantHandleException:
... # topic not for this subscription; continue routing Prevention
- Subscribe to the exact topic type string publishers emit — remember TypeSubscription matches by equality, not prefix.
- Centralize topic type constants shared by publisher and subscriber code to avoid typos.
When it happens
Trigger: Directly calling `sub.map_to_agent(TopicId("events.created", "src"))` on a TypeSubscription with topic_type "events" — 'events.created' != 'events', so it raises. Common when a topic type carries a suffix/namespace the subscription was not registered for.
Common situations: Custom routers iterating subscriptions manually; publishing to hierarchical topic types ("events.created") while subscribed to the bare type ("events") — for prefix behavior use TypePrefixSubscription; casing or whitespace mismatches between publisher and subscriber config.
Related errors
- TopicId does not match the subscription
- Return type {type(return_value)} is not None.
- Subscription already exists
- Subscription does not exist
- SubscriptionInstantiationContext cannot be instantiated. It
AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15).
Data as JSON: /api/errors/03892707a4bc2a6a.
Report an issue: GitHub.