{"record":{"id":"92e268bd973777c6","repo":"microsoft/semantic-kernel","slug":"topicid-does-not-match-the-subscription-92e268","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/semantic_kernel/agents/runtime/in_process/type_prefix_subscription.py","lineNumber":56,"sourceCode":"\n    @property\n    def topic_type_prefix(self) -> str:\n        \"\"\"Get the topic type prefix of the subscription.\"\"\"\n        return self._topic_type_prefix\n\n    @property\n    def agent_type(self) -> str:\n        \"\"\"Get the agent type of the subscription.\"\"\"\n        return self._agent_type\n\n    def is_match(self, topic_id: TopicId) -> bool:\n        \"\"\"Check if the topic_id matches the subscription.\"\"\"\n        return topic_id.type.startswith(self._topic_type_prefix)\n\n    def map_to_agent(self, topic_id: TopicId) -> AgentId:\n        \"\"\"Map the topic_id to an agent_id.\"\"\"\n        if not self.is_match(topic_id):\n            raise CantHandleException(\"TopicId does not match the subscription\")\n\n        return CoreAgentId(type=self._agent_type, key=topic_id.source)\n\n    def __eq__(self, other: object) -> bool:\n        \"\"\"Check if two subscriptions are equal.\"\"\"\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":38,"sourceCodeEnd":68,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/runtime/in_process/type_prefix_subscription.py#L38-L68","documentation":"TypePrefixSubscription.map_to_agent first calls is_match, which requires topic_id.type to start with the subscription's topic_type_prefix (startswith). On a miss it raises CantHandleException before building the AgentId, signaling the subscription will not route this topic.","triggerScenarios":"A message is published to a topic whose `type` does not begin with the registered prefix, or map_to_agent is called manually with a topic that fails `topic_id.type.startswith(self._topic_type_prefix)`.","commonSituations":"Prefix typo or casing mismatch between publisher and subscription; publishing to a sibling topic (e.g. prefix \"chat\" but topic type \"summary\"); subscription registered against the wrong prefix.","solutions":["Ensure the published topic type starts with the exact prefix, e.g. prefix 'chat' matches topic type 'chat.user' but not 'summary'.","Register the TypePrefixSubscription with the prefix that matches your published topic types.","Call `sub.is_match(topic_id)` before map_to_agent to filter or route gracefully."],"exampleFix":"// before\nsub = TypePrefixSubscription(id=\"s\", topic_type_prefix=\"chat\", agent_type=\"Bot\")\ntopic = TopicId(type=\"summary\", source=\"s1\")  # does not start with 'chat'\nagent_id = sub.map_to_agent(topic)  # CantHandleException\n\n// after\ntopic = TopicId(type=\"chat.user\", source=\"s1\")  # starts with 'chat'\nagent_id = sub.map_to_agent(topic)","handlingStrategy":"type-guard","validationCode":"if not sub.is_match(topic_id):\n    raise ValueError(f\"topic {topic_id.type} does not start with prefix {sub.topic_type_prefix}; skipping\")\nagent_id = sub.map_to_agent(topic_id)","typeGuard":"def can_route_prefix(sub: TypePrefixSubscription, topic_id: TopicId) -> bool:\n    return topic_id.type.startswith(sub.topic_type_prefix)","tryCatchPattern":"from semantic_kernel.exceptions import CantHandleException\ntry:\n    agent_id = sub.map_to_agent(topic_id)\nexcept CantHandleException:\n    continue  # this subscription does not handle the topic","preventionTips":["Keep publisher topic-type prefixes and subscription prefixes in a shared constant","Call is_match before map_to_agent","Use TypePrefixSubscription for flexible routing, TypeSubscription for exact"],"tags":["subscriptions","agent-runtime","messaging","routing"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}