microsoft/semantic-kernel · warning · CantHandleException

TopicId does not match the subscription

Error message

TopicId does not match the subscription

What it means

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.

Source

Thrown at python/semantic_kernel/agents/runtime/in_process/type_prefix_subscription.py:56

    @property
    def topic_type_prefix(self) -> str:
        """Get the topic type prefix of the subscription."""
        return self._topic_type_prefix

    @property
    def agent_type(self) -> str:
        """Get the agent type of the subscription."""
        return self._agent_type

    def is_match(self, topic_id: TopicId) -> bool:
        """Check if the topic_id matches the subscription."""
        return topic_id.type.startswith(self._topic_type_prefix)

    def map_to_agent(self, topic_id: TopicId) -> AgentId:
        """Map the topic_id to an agent_id."""
        if not self.is_match(topic_id):
            raise CantHandleException("TopicId does not match the subscription")

        return CoreAgentId(type=self._agent_type, key=topic_id.source)

    def __eq__(self, other: object) -> bool:
        """Check if two subscriptions are equal."""
        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 c028a0c7dc)

Solutions

1. Ensure the published topic type starts with the exact prefix, e.g. prefix 'chat' matches topic type 'chat.user' but not 'summary'.
2. Register the TypePrefixSubscription with the prefix that matches your published topic types.
3. Call `sub.is_match(topic_id)` before map_to_agent to filter or route gracefully.

Example fix

// before
sub = TypePrefixSubscription(id="s", topic_type_prefix="chat", agent_type="Bot")
topic = TopicId(type="summary", source="s1")  # does not start with 'chat'
agent_id = sub.map_to_agent(topic)  # CantHandleException

// after
topic = TopicId(type="chat.user", source="s1")  # starts with 'chat'
agent_id = sub.map_to_agent(topic)

if not sub.is_match(topic_id):
    raise ValueError(f"topic {topic_id.type} does not start with prefix {sub.topic_type_prefix}; skipping")
agent_id = sub.map_to_agent(topic_id)

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

from semantic_kernel.exceptions import CantHandleException
try:
    agent_id = sub.map_to_agent(topic_id)
except CantHandleException:
    continue  # this subscription does not handle the topic

When it happens

Trigger: 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)`.

Common situations: 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.

Related errors

• TopicId does not match the subscription
• Subscription does not exist
• Delivery of message {messageId} was cancelled.
• Message must have a topic to be published.
• Message must have a receiver to be sent.

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/92e268bd973777c6. Report an issue: GitHub.