microsoft/autogen · error · ValueError

Subscription already exists

Error message

Subscription already exists

What it means

Raised by SubscriptionManager.add_subscription when an identical Subscription (matched via __eq__) is already registered with the runtime. The manager keeps a list of subscriptions and rejects exact duplicates to avoid delivering the same topic messages to an agent twice. It is a ValueError thrown synchronously inside the async add_subscription call.

Source

Thrown at python/packages/autogen-core/src/autogen_core/_runtime_impl_helpers.py:45

        await instance_getter(id)

    return id


class SubscriptionManager:
    def __init__(self) -> None:
        self._subscriptions: List[Subscription] = []
        self._seen_topics: Set[TopicId] = set()
        self._subscribed_recipients: DefaultDict[TopicId, List[AgentId]] = defaultdict(list)

    @property
    def subscriptions(self) -> Sequence[Subscription]:
        return self._subscriptions

    async def add_subscription(self, subscription: Subscription) -> None:
        # Check if the subscription already exists
        if any(sub == subscription for sub in self._subscriptions):
            raise ValueError("Subscription already exists")

        self._subscriptions.append(subscription)
        self._rebuild_subscriptions(self._seen_topics)

    async def remove_subscription(self, id: str) -> None:
        # Check if the subscription exists
        if not any(sub.id == id for sub in self._subscriptions):
            raise ValueError("Subscription does not exist")

        def is_not_sub(x: Subscription) -> bool:
            return x.id != id

        self._subscriptions = list(filter(is_not_sub, self._subscriptions))

        # Rebuild the subscriptions
        self._rebuild_subscriptions(self._seen_topics)

    async def get_subscribed_recipients(self, topic: TopicId) -> List[AgentId]:

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Remove the existing subscription first: await runtime.remove_subscription(existing_sub.id), then add the new one
2. Pass skip_class_subscriptions=True when registering the agent if you intend to manage its subscriptions manually
3. Generate a unique subscription id (e.g. str(uuid.uuid4())) when you genuinely need two similar subscriptions that differ only in intent
4. Before adding, check any(s.id == new.id or s == new for s in runtime.subscription_manager.subscriptions)

Example fix

// before
await runtime.add_subscription(TypeSubscription(topic_type="tasks", agent_type="worker"))
# ...later, same line again -> ValueError

// after
await runtime.add_subscription(
    TypeSubscription(id=str(uuid.uuid4()), topic_type="tasks", agent_type="worker")
)

async def safe_add_subscription(runtime, new_sub):
    from autogen_core import Subscription
    existing = runtime.subscription_manager.subscriptions
    if any(sub == new_sub or sub.id == new_sub.id for sub in existing):
        return False  # already present
    await runtime.add_subscription(new_sub)
    return True

try:
    await runtime.add_subscription(sub)
except ValueError as e:
    if "already exists" in str(e):
        logger.debug("subscription %s already registered", sub.id)
    else:
        raise

When it happens

Trigger: Calling runtime.add_subscription (or RuntimeAgentType registration that auto-adds class subscriptions) with a Subscription equal (source_topic_type, map/target, and id) to one already registered. Typical with TypeSubscription(agent_type=..., topic_type=...) added twice, e.g. once manually and once automatically by agent registration with skip_class_subscriptions left False.

Common situations: Registering the same agent type on two topics where DefaultSubscription/TypeSubscription overlap; adding a manual subscription for a topic the agent class already subscribes to via class-based subscriptions; retry logic that re-runs registration code without tracking prior success.

Related errors

• Subscription does not exist
• Subscription with id {subscription.Id} already exists.
• Agent with type {type} already exists.
• TopicId does not match the subscription
• TopicId does not match the subscription

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/4da487b740836212. Report an issue: GitHub.