microsoft/semantic-kernel · warning · CantHandleException

TopicId does not match the subscription

Error message

TopicId does not match the subscription

What it means

TypeSubscription.map_to_agent first calls is_match, which requires topic_id.type to exactly equal the subscription's topic_type. On a miss it raises CantHandleException before building the AgentId.

Source

Thrown at python/semantic_kernel/agents/runtime/in_process/type_subscription.py:58

    @property
    def topic_type(self) -> str:
        """Get the topic type of the subscription."""
        return self._topic_type

    @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 == self._topic_type

    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, 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 c028a0c7dc)

Solutions

1. Make the published topic type exactly equal the subscription's topic_type string.
2. If you need partial/flexible matching, switch to TypePrefixSubscription.
3. Guard with `sub.is_match(topic_id)` before mapping.

Example fix

// before
sub = TypeSubscription(id="s", topic_type="chat", agent_type="Bot")
topic = TopicId(type="chat.user", source="s1")  # not exactly 'chat'
agent_id = sub.map_to_agent(topic)  # CantHandleException

// after
topic = TopicId(type="chat", source="s1")  # exact match
agent_id = sub.map_to_agent(topic)

if not sub.is_match(topic_id):
    raise ValueError(f"topic {topic_id.type} != {sub.topic_type}; skipping")
agent_id = sub.map_to_agent(topic_id)

def can_route_exact(sub: TypeSubscription, topic_id: TopicId) -> bool:
    return topic_id.type == sub.topic_type

from semantic_kernel.exceptions import CantHandleException
try:
    agent_id = sub.map_to_agent(topic_id)
except CantHandleException:
    continue

When it happens

Trigger: A message published to a topic whose `type` is not exactly equal to the registered topic_type, or map_to_agent called with a mismatched topic (fails `topic_id.type == self._topic_type`).

Common situations: Exact string mismatch (extra segment, casing, trailing whitespace) between the published topic type and the subscription topic_type; using TypeSubscription where prefix matching was intended (use TypePrefixSubscription instead).

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