langchain-ai/langgraph · error · TypeError

stream_events(version='v3') transformers must be scope-aware

Error message

stream_events(version='v3') transformers must be scope-aware callables, got pre-built instance {type(spec).__name__}. Pass the transformer class or a factory like `lambda scope: MyTransformer(scope, ...)`.

What it means

Error "stream_events(version='v3') transformers must be scope-aware callables, got pre-built instance {type(spec).__name__}. Pass the transformer class or a factory like `lambda scope: MyTransformer(scope, ...)`." thrown in langchain-ai/langgraph.

Source

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

        )
    return list(modes)


def _normalize_stream_transformer_factories(
    specs: Sequence[Callable[[tuple[str, ...]], Any]] | None,
) -> list[Callable[[tuple[str, ...]], Any]]:
    """Normalize stream transformer specs to scoped factories.

    A stream transformer spec is a callable that accepts
    `scope: tuple[str, ...]` and returns a fresh `StreamTransformer`.
    Transformer classes work when their constructor follows the same
    shape. Pre-built instances are rejected because they cannot be
    cloned into subgraph scopes.
    """
    factories: list[Callable[[tuple[str, ...]], Any]] = []
    for spec in specs or ():
        if isinstance(spec, StreamTransformer):
            raise TypeError(
                "stream_events(version='v3') transformers must be scope-aware callables, "
                f"got pre-built instance {type(spec).__name__}. Pass the "
                "transformer class or a factory like "
                "`lambda scope: MyTransformer(scope, ...)`."
            )
        if not callable(spec):
            raise TypeError(
                "stream_events(version='v3') transformers must be scope-aware callables, "
                f"got {type(spec).__name__}."
            )

        def factory(scope: tuple[str, ...], _spec: Callable[..., Any] = spec) -> Any:
            return _spec(scope)

        factories.append(factory)
    return factories

View on GitHub (pinned to 38031739e5)

When it happens

Trigger: Thrown at libs/langgraph/langgraph/pregel/main.py:431 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/9f7e6baebe0cab82. Report an issue: GitHub.