{"record":{"id":"c8457d4e442b732e","repo":"microsoft/autogen","slug":"topicid-does-not-match-the-subscription-c8457d","errorCode":null,"errorMessage":"TopicId does not match the subscription","messagePattern":"TopicId does not match the subscription","errorType":"exception","errorClass":"CantHandleException","httpStatus":null,"severity":"warning","filePath":"python/packages/autogen-core/src/autogen_core/_type_prefix_subscription.py","lineNumber":59,"sourceCode":"\n    @property\n    def id(self) -> str:\n        return self._id\n\n    @property\n    def topic_type_prefix(self) -> str:\n        return self._topic_type_prefix\n\n    @property\n    def agent_type(self) -> str:\n        return self._agent_type\n\n    def is_match(self, topic_id: TopicId) -> bool:\n        return topic_id.type.startswith(self._topic_type_prefix)\n\n    def map_to_agent(self, topic_id: TopicId) -> AgentId:\n        if not self.is_match(topic_id):\n            raise CantHandleException(\"TopicId does not match the subscription\")\n\n        return AgentId(type=self._agent_type, key=topic_id.source)\n\n    def __eq__(self, other: object) -> bool:\n        if not isinstance(other, TypePrefixSubscription):\n            return False\n\n        return self.id == other.id or (\n            self.agent_type == other.agent_type and self.topic_type_prefix == other.topic_type_prefix\n        )\n","sourceCodeStart":41,"sourceCodeEnd":70,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-core/src/autogen_core/_type_prefix_subscription.py#L41-L70","documentation":"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.","triggerScenarios":"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().","commonSituations":"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.","solutions":["Always gate the call: `if sub.is_match(topic_id): agent_id = sub.map_to_agent(topic_id)`.","Catch CantHandleException (from autogen_core.exceptions / CantHandleException) when iterating several subscriptions and skip that one.","Check the prefix vs the topic type string for typos or casing differences (matching is case-sensitive)."],"exampleFix":"# before\nagent_id = sub.map_to_agent(TopicId(\"notifications\", \"x\"))  # CantHandleException\n\n# after\nif sub.is_match(topic_id):\n    agent_id = sub.map_to_agent(topic_id)\nelse:\n    continue  # try next subscription","handlingStrategy":"type-guard","validationCode":"if sub.is_match(topic_id):\n    agent_id = sub.map_to_agent(topic_id)\nelse:\n    skip(sub)  # subscription cannot route this topic","typeGuard":"def can_map_prefix_sub(sub: TypePrefixSubscription, topic_id: TopicId) -> bool:\n    return topic_id.type.startswith(sub.topic_type_prefix)","tryCatchPattern":"from autogen_core.exceptions import CantHandleException\n\nfor sub in subscriptions:\n    try:\n        agent_id = sub.map_to_agent(topic_id)\n        break\n    except CantHandleException:\n        continue","preventionTips":["Prefer is_match() over map_to_agent() when probing subscriptions.","Use TypePrefixSubscription for hierarchical topic types and keep prefixes consistent (e.g. always 'events.')."],"tags":["python","autogen-core","subscriptions","pubsub","routing"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}