deepset-ai/haystack · error · ValueError

break_point {break_point} is not a registered component in t

Error message

break_point {break_point} is not a registered component in the pipeline

What it means

_validate_break_point_against_pipeline raises a plain ValueError when the break_point of a PipelineSnapshot (or debug run) names a component that is not a node of the current pipeline's graph. Breakpoints must reference existing components so the runner knows where to pause.

Source

Thrown at haystack/core/pipeline/breakpoint.py:52

    pipeline snapshots are saved to files. By default (when the variable is not set),
    saving is disabled. Only "true" and "1" (case-insensitive) enable saving; any other value disables it.

    :returns: True if snapshot saving is enabled, False otherwise.
    """
    value = os.environ.get(HAYSTACK_PIPELINE_SNAPSHOT_SAVE_ENABLED, "false").lower()
    return value in ("true", "1")


def _validate_break_point_against_pipeline(break_point: Breakpoint, graph: MultiDiGraph) -> None:
    """
    Validates the breakpoints passed to the pipeline.

    Makes sure the breakpoint contains a valid components registered in the pipeline.

    :param break_point: a breakpoint to validate
    """
    if break_point.component_name not in graph.nodes:
        raise ValueError(f"break_point {break_point} is not a registered component in the pipeline")


def _validate_pipeline_snapshot_against_pipeline(pipeline_snapshot: PipelineSnapshot, graph: MultiDiGraph) -> None:
    """
    Validates that the pipeline_snapshot contains valid configuration for the current pipeline.

    Raises a PipelineInvalidPipelineSnapshotError if any component in pipeline_snapshot is not part of the
    target pipeline.

    :param pipeline_snapshot: The saved state to validate.
    """

    pipeline_state = pipeline_snapshot.pipeline_state
    valid_components = set(graph.nodes.keys())

    # Check if the ordered_component_names are valid components in the pipeline
    invalid_ordered_components = set(pipeline_snapshot.ordered_component_names) - valid_components
    if invalid_ordered_components:

View on GitHub (pinned to e318778c9b)

Solutions

Correct break_point.component_name to an existing component name (list them via pipeline.components or pipeline.graph.nodes).
Regenerate the snapshot/breakpoint against the current pipeline if components were renamed.
Validate the name before running: check `name in pipeline.graph.nodes`.

Example fix

// before
break_point = Breakpoint(component_name="retrievr", visit_count=1)
// after
break_point = Breakpoint(component_name="retriever", visit_count=1)

Defensive patterns

Strategy: validation

Validate before calling

assert break_point.component_name in pipeline.graph.nodes, f"{break_point.component_name} not in pipeline"

Type guard

def is_valid_breakpoint(bp, pipeline) -> bool:
    return bp.component_name in pipeline.graph.nodes

Try / catch

try:
    result = pipeline.run(data, break_point=bp)
except ValueError as e:
    logger.error("Bad breakpoint: %s", e)

Prevention

Source component names from pipeline.graph.nodes, not string literals
Regenerate breakpoints after renaming pipeline components
Never share breakpoints between differently-defined pipelines

When it happens

Trigger: Calling pipeline.run(..., break_point=Breakpoint(component_name="typo")) with a misspelled or renamed component; resuming with a snapshot produced by a different/older pipeline whose component set differs.

Common situations: Renaming components after saving breakpoints; typos in component_name; sharing snapshots between pipelines that were edited between runs.

Related errors

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