microsoft/autogen · warning · CantHandleException

TopicId does not match the subscription

Error message

TopicId does not match the subscription

What it means

TypePrefixSubscription.map_to_agent() guards itself with is_match(): the topic type must start with the subscription's topic_type_prefix. If it does not, it raises CantHandleException — a control-flow signal the subscription infrastructure uses to skip subscriptions that cannot route a given topic. Hitting it as a user means you called map_to_agent on a subscription for a topic outside its prefix.

Source

Thrown at python/packages/autogen-core/src/autogen_core/_type_prefix_subscription.py:59

    @property
    def id(self) -> str:
        return self._id

    @property
    def topic_type_prefix(self) -> str:
        return self._topic_type_prefix

    @property
    def agent_type(self) -> str:
        return self._agent_type

    def is_match(self, topic_id: TopicId) -> bool:
        return topic_id.type.startswith(self._topic_type_prefix)

    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, TypePrefixSubscription):
            return False

        return self.id == other.id or (
            self.agent_type == other.agent_type and self.topic_type_prefix == other.topic_type_prefix
        )

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Always gate the call: `if sub.is_match(topic_id): agent_id = sub.map_to_agent(topic_id)`.
2. Catch CantHandleException (from autogen_core.exceptions / CantHandleException) when iterating several subscriptions and skip that one.
3. Check the prefix vs the topic type string for typos or casing differences (matching is case-sensitive).

Example fix

# before
agent_id = sub.map_to_agent(TopicId("notifications", "x"))  # CantHandleException

# after
if sub.is_match(topic_id):
    agent_id = sub.map_to_agent(topic_id)
else:
    continue  # try next subscription

if sub.is_match(topic_id):
    agent_id = sub.map_to_agent(topic_id)
else:
    skip(sub)  # subscription cannot route this topic

def can_map_prefix_sub(sub: TypePrefixSubscription, topic_id: TopicId) -> bool:
    return topic_id.type.startswith(sub.topic_type_prefix)

from autogen_core.exceptions import CantHandleException

for sub in subscriptions:
    try:
        agent_id = sub.map_to_agent(topic_id)
        break
    except CantHandleException:
        continue

When it happens

Trigger: Directly calling `subscription.map_to_agent(TopicId("notifications", "src"))` on a TypePrefixSubscription with prefix "events." — 'notifications' does not start with 'events.', so it raises. Also custom subscription-router code that iterates subscriptions and maps without pre-filtering with is_match().

Common situations: Writing custom routing logic instead of letting the runtime's subscription manager route publications; typos in the prefix or topic type; assuming exact-type subscriptions semantics while using the prefix variant.

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/c8457d4e442b732e. Report an issue: GitHub.