deepset-ai/haystack · error · ValueError

'_debug' is a reserved name for debug output. Choose another

Error message

'_debug' is a reserved name for debug output. Choose another name.

What it means

The name '_debug' is reserved by Pipeline for debug output nodes. Using it as a component name would clash with internal machinery, so _validate_component raises ValueError immediately.

Source

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

            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)
                msg = (
                    f"Component has already been added to this Pipeline under the name '{existing_name}'. "
                    "A component instance can only be added once."
                )

View on GitHub (pinned to e318778c9b)

Solutions

1. Rename the component to anything other than '_debug', e.g. 'debug' or 'my_debug'
2. If writing a generator, validate/escape names against the reserved list before adding

Example fix

// before
pipe.add_component("_debug", MyComp())
// after
pipe.add_component("debug", MyComp())

RESERVED = {"_debug"}
def is_valid_name(name: str) -> bool:
    return name not in RESERVED

def is_usable_component_name(name: str) -> bool:
    return isinstance(name, str) and name != "_debug" and "." not in name

try:
    pipe.add_component(name, comp)
except ValueError as e:
    if "reserved name" in str(e):
        name = name.lstrip("_")
        pipe.add_component(name, comp)
    else:
        raise

When it happens

Trigger: pipe.add_component("_debug", comp) or including "_debug" as a key in add_components(); generating names programmatically that resolve to '_debug'.

Common situations: Users following debug-output examples and accidentally naming their own component '_debug'; template expansion producing reserved names.

Related errors

• A component named '{name}' already exists in this pipeline:
• {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/667ad39b680c1867. Report an issue: GitHub.