{"record":{"id":"667ad39b680c1867","repo":"deepset-ai/haystack","slug":"debug-is-a-reserved-name-for-debug-output-choo","errorCode":null,"errorMessage":"'_debug' is a reserved name for debug output. Choose another name.","messagePattern":"'_debug' is a reserved name for debug output\\. Choose another name\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"haystack/core/pipeline/base.py","lineNumber":482,"sourceCode":"            component_names_by_id[instance_id] = name\n            components_to_add.append((name, instance))\n\n        for name, instance in components_to_add:\n            self._add_component_to_graph(name, instance)\n\n        return self\n\n    def _validate_component(self, name: str, instance: Component) -> bool:\n        \"\"\"Validate a component before adding it, returning whether it needs to be added.\"\"\"\n        # Component names are unique\n        if name in self.graph.nodes:\n            if self.graph.nodes[name][\"instance\"] is instance:\n                return False\n            raise ValueError(f\"A component named '{name}' already exists in this pipeline: choose another name.\")\n\n        # Components can't be named `_debug`\n        if name == \"_debug\":\n            raise ValueError(\"'_debug' is a reserved name for debug output. Choose another name.\")\n\n        # Component names can't have \".\"\n        if \".\" in name:\n            raise ValueError(f\"{name} is an invalid component name, cannot contain '.' (dot) characters.\")\n\n        # Component instances must be components\n        if not isinstance(instance, Component):\n            raise PipelineValidationError(\n                f\"'{type(instance)}' doesn't seem to be a component. Is this class decorated with @component?\"\n            )\n\n        if owning_pipeline := getattr(instance, \"__haystack_added_to_pipeline__\", None):\n            if owning_pipeline is self:\n                existing_name = self.get_component_name(instance)\n                msg = (\n                    f\"Component has already been added to this Pipeline under the name '{existing_name}'. \"\n                    \"A component instance can only be added once.\"\n                )","sourceCodeStart":464,"sourceCodeEnd":500,"githubUrl":"https://github.com/deepset-ai/haystack/blob/e318778c9bf60a1963e3b5f451359655dd696c30/haystack/core/pipeline/base.py#L464-L500","documentation":"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.","triggerScenarios":"pipe.add_component(\"_debug\", comp) or including \"_debug\" as a key in add_components(); generating names programmatically that resolve to '_debug'.","commonSituations":"Users following debug-output examples and accidentally naming their own component '_debug'; template expansion producing reserved names.","solutions":["Rename the component to anything other than '_debug', e.g. 'debug' or 'my_debug'","If writing a generator, validate/escape names against the reserved list before adding"],"exampleFix":"// before\npipe.add_component(\"_debug\", MyComp())\n// after\npipe.add_component(\"debug\", MyComp())","handlingStrategy":"validation","validationCode":"RESERVED = {\"_debug\"}\ndef is_valid_name(name: str) -> bool:\n    return name not in RESERVED","typeGuard":"def is_usable_component_name(name: str) -> bool:\n    return isinstance(name, str) and name != \"_debug\" and \".\" not in name","tryCatchPattern":"try:\n    pipe.add_component(name, comp)\nexcept ValueError as e:\n    if \"reserved name\" in str(e):\n        name = name.lstrip(\"_\")\n        pipe.add_component(name, comp)\n    else:\n        raise","preventionTips":["Maintain a list of reserved names and validate generated names against it","Prefix internal/debug components with something other than a leading underscore","Add a unit test asserting generated names never equal '_debug'"],"tags":["python","pipeline","naming-conflict"],"backgroundTag":"reserved-identifier","analyzedSha":"e318778c9bf60a1963e3b5f451359655dd696c30","analyzedAt":"2026-08-30T11:45:20.711Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}