deepset-ai/haystack · error · ValueError

Unknown components in streaming_components: {sorted(unknown)

Error message

Unknown components in streaming_components: {sorted(unknown)}

What it means

Pipeline.stream validates the streaming_components list (pipeline.py:1301): every name must correspond to a node in the pipeline graph. A ValueError listing the unknown names is raised before streaming starts. This catches typos and components added under different names.

Source

Thrown at haystack/core/pipeline/pipeline.py:1301

        :raises PipelineRuntimeError:
            Surfaced during iteration. If the Pipeline contains cycles with unsupported connections that would cause
            it to get stuck and fail running, or if a Component fails or returns output in an unsupported type.
        :raises PipelineMaxComponentRuns:
            Surfaced during iteration. If a Component reaches the maximum number of times it can be run in this
            Pipeline.
        """
        streaming_capable = {
            name
            for name in self.graph.nodes
            if getattr(self.graph.nodes[name]["instance"], "__haystack_supports_async__", False)
            and "streaming_callback" in self.graph.nodes[name]["instance"].__haystack_input__
        }
        if streaming_components is not None:
            requested = set(streaming_components)
            unknown = requested - set(self.graph.nodes)
            non_streaming = requested - unknown - streaming_capable
            if unknown:
                raise ValueError(f"Unknown components in streaming_components: {sorted(unknown)}")
            if non_streaming:
                raise ValueError(f"These components do not support streaming: {sorted(non_streaming)}")

        queue: asyncio.Queue[StreamingChunk | _EndOfStream] = asyncio.Queue()

        def make_forwarder(user_callback: StreamingCallbackT | None) -> AsyncStreamingCallbackT:
            async def forwarder(chunk: StreamingChunk) -> None:
                await queue.put(chunk)
                if user_callback is not None:
                    await _invoke_streaming_callback(user_callback, chunk)

            return forwarder

        new_data: dict[str, Any] = self._prepare_component_input_data(data)
        for name in streaming_capable:
            if streaming_components is not None and name not in streaming_components:
                continue
            instance = self.graph.nodes[name]["instance"]

View on GitHub (pinned to e318778c9b)

Solutions

Use exact component names as passed to pipeline.add_component().
List pipeline.graph.nodes (or the component sockets) to discover valid names at runtime.
Filter the requested list against set(pipe.graph.nodes) before calling stream.

Example fix

# before
stream = pipe.stream(data, streaming_components=["gpt"])
# after
names = [n for n in ["gpt"] if n in pipe.graph.nodes]
stream = pipe.stream(data, streaming_components=names)

Defensive patterns

Strategy: validation

Validate before calling

valid = set(pipe.graph.nodes)
requested = set(streaming_components or [])
unknown = requested - valid
if unknown:
    raise ValueError(f'fix names: {sorted(unknown)}')

Try / catch

try:
    stream = pipe.stream(data, streaming_components=names)
except ValueError as e:
    if 'Unknown components' in str(e):
        print(e)  # message lists the offending names sorted

Prevention

Derive component names from the same constants used in add_component().
Print pipe.graph.nodes when building streaming_components dynamically.
Watch case sensitivity in component names.

When it happens

Trigger: pipe.stream(data, streaming_components=["chatgenerator"]) when the component was added as "llm"; stale names after renaming a component or refactoring the pipeline.

Common situations: Case-sensitivity mistakes in component names; hard-coded component names in config that no longer match add_component() names; copying examples with different component names.

Related errors

AI-assisted analysis of deepset-ai/haystack@e318778c9b (2026-08-30). Data as JSON: /api/errors/a2d642018fed938d. Report an issue: GitHub.