langchain-ai/langgraph · error · ValueError

Cannot subscribe to single channels when other channels are…

Error message

Cannot subscribe to single channels when other channels are already subscribed to

What it means

Raised by a Pregel node builder's subscribe_only when the builder already subscribes to other channels. subscribe_only replaces prior subscriptions and cannot be mixed with existing subscribe_to calls on the same builder — the internal representation (string vs list) would be inconsistent. Use one subscription style per node.

Solutions

1. Call subscribe_only before any subscribe() calls
2. Drop subscribe_only and list the single channel via subscribe() instead

When it happens

Trigger: Thrown at libs/langgraph/langgraph/pregel/main.py:250 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of langchain-ai/langgraph@38031739e5 (2026-08-26). Data as JSON: /api/errors/d2b11808bd2210f2. Report an issue: GitHub.

Appendix: source

Thrown at libs/langgraph/langgraph/pregel/main.py:250

        self._channels = []
        self._triggers = []
        self._tags = []
        self._metadata = {}
        self._writes = []
        self._bound = DEFAULT_BOUND
        self._retry_policy = []
        self._cache_policy = None
        self._timeout = None

    def subscribe_only(
        self,
        channel: str,
    ) -> Self:
        """Subscribe to a single channel."""
        if not self._channels:
            self._channels = channel
        else:
            raise ValueError(
                "Cannot subscribe to single channels when other channels are already subscribed to"
            )

        self._triggers.append(channel)

        return self

    def subscribe_to(
        self,
        *channels: str,
        read: bool = True,
    ) -> Self:
        """Add channels to subscribe to.

        Node will be invoked when any of these channels are updated, with a dict of the
        channel values as input.

        Args:

View on GitHub (pinned to 38031739e5)