deepset-ai/haystack · error · ValueError

A component named '{name}' already exists in this pipeline:

Error message

A component named '{name}' already exists in this pipeline: choose another name.

What it means

Pipeline component names are unique node identifiers in the underlying graph. add_component() raises ValueError when the requested name already exists and the provided instance is not the exact instance already registered under that name (re-adding the same instance is silently a no-op, handled by _validate_component returning False).

Source

Thrown at haystack/core/pipeline/base.py:478

                    f"Component instance cannot be added to the pipeline more than once. "
                    f"It is mapped to both '{previous_name}' and '{name}'."
                )

            component_names_by_id[instance_id] = name
            components_to_add.append((name, instance))

        for name, instance in components_to_add:
            self._add_component_to_graph(name, instance)

        return self

    def _validate_component(self, name: str, instance: Component) -> bool:
        """Validate a component before adding it, returning whether it needs to be added."""
        # Component names are unique
        if name in self.graph.nodes:
            if self.graph.nodes[name]["instance"] is instance:
                return False
            raise ValueError(f"A component named '{name}' already exists in this pipeline: choose another name.")

        # Components can't be named `_debug`
        if name == "_debug":
            raise ValueError("'_debug' is a reserved name for debug output. Choose another name.")

        # Component names can't have "."
        if "." in name:
            raise ValueError(f"{name} is an invalid component name, cannot contain '.' (dot) characters.")

        # Component instances must be components
        if not isinstance(instance, Component):
            raise PipelineValidationError(
                f"'{type(instance)}' doesn't seem to be a component. Is this class decorated with @component?"
            )

        if owning_pipeline := getattr(instance, "__haystack_added_to_pipeline__", None):
            if owning_pipeline is self:
                existing_name = self.get_component_name(instance)

View on GitHub (pinned to e318778c9b)

Solutions

1. Choose a unique name for the new component
2. Remove the existing component first with pipe.remove_component(name) then re-add
3. If the instance is identical, skip the call — adding the same instance under the same name is a no-op
4. In notebooks, restart the kernel or recreate the Pipeline object

Example fix

// before
pipe.add_component("ranker", Ranker(top_k=5))  # 'ranker' exists
// after
pipe.remove_component("ranker")
pipe.add_component("ranker", Ranker(top_k=5))

def can_add(pipe, name: str, instance) -> bool:
    if name in pipe.graph.nodes:
        return pipe.graph.nodes[name]["instance"] is instance
    return True

def is_new_or_same(pipe, name: str, instance) -> bool:
    return name not in pipe.graph.nodes or pipe.graph.nodes[name]["instance"] is instance

try:
    pipe.add_component(name, comp)
except ValueError as e:
    if "already exists" in str(e):
        pipe.remove_component(name)
        pipe.add_component(name, comp)
    else:
        raise

When it happens

Trigger: pipe.add_component("retriever", r1) after "retriever" already holds a different instance; re-running notebook cells that re-add components under the same names; loops that add components with fixed names.

Common situations: Jupyter notebooks executed multiple times; templated pipeline builders where names collide; migration scripts re-registering components.

Related errors

• '_debug' is a reserved name for debug output. Choose another
• {name} is an invalid component name, cannot contain '.' (dot
• MarkdownHeaderSplitter only works with text documents but co
• Error while unmarshalling serialized pipeline data. This is
• Component instance cannot be added to the pipeline more than

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