deepset-ai/haystack · error · ValueError

{name} is an invalid component name, cannot contain '.' (dot

Error message

{name} is an invalid component name, cannot contain '.' (dot) characters.

What it means

Component names are used to build socket references like 'component.socket' in connect(), so they cannot contain dots. A name containing '.' makes socket parsing ambiguous and is rejected with ValueError.

Source

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

            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."
                )
            else:
                msg = (
                    "Component has already been added in another Pipeline. "
                    "Components can't be shared between Pipelines. Create a new instance instead."

View on GitHub (pinned to e318778c9b)

Solutions

1. Replace '.' with '_' in the component name
2. Sanitize generated names: name.replace('.', '_') before add_component
3. Use a delimiter other than '.' for your own naming scheme

Example fix

// before
pipe.add_component("pre.retriever", retriever)
// after
pipe.add_component("pre_retriever", retriever)

def sanitize_name(name: str) -> str:
    return name.replace(".", "_")

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

try:
    pipe.add_component(name, comp)
except ValueError as e:
    if "cannot contain '.'" in str(e):
        pipe.add_component(name.replace(".", "_"), comp)
    else:
        raise

When it happens

Trigger: pipe.add_component("my.component", comp) or add_components with dotted keys; deriving names from module paths or file names that contain dots.

Common situations: Auto-naming components from Python module paths (e.g. 'foo.bar.Comp'); users mirroring YAML key conventions with dots.

Related errors

• A component named '{name}' already exists in this pipeline:
• '_debug' is a reserved name for debug output. Choose another
• 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/a92737af091a8051. Report an issue: GitHub.