deepset-ai/haystack · error · ValueError

Either pipeline_snapshot or break_point must be provided.

Error message

Either pipeline_snapshot or break_point must be provided.

What it means

A BreakpointException carries pipeline state for resuming, so it must know either an in-memory pipeline_snapshot or a break_point from which a snapshot can be loaded. The constructor raises ValueError when both are None because the exception would have no state to resume from.

Source

Thrown at haystack/core/errors.py:127

    """

    def __init__(
        self,
        message: str,
        component: str | None = None,
        pipeline_snapshot: PipelineSnapshot | None = None,
        pipeline_snapshot_file_path: str | None = None,
        *,
        break_point: Breakpoint | None = None,
    ) -> None:
        super().__init__(message)
        self.component = component
        self.pipeline_snapshot = pipeline_snapshot
        self.pipeline_snapshot_file_path = pipeline_snapshot_file_path
        self._break_point = break_point

        if self.pipeline_snapshot is None and self._break_point is None:
            raise ValueError("Either pipeline_snapshot or break_point must be provided.")

    @classmethod
    def from_triggered_breakpoint(cls, break_point: Breakpoint) -> "BreakpointException":
        """
        Create a BreakpointException from a triggered breakpoint.
        """
        msg = f"Breaking at component {break_point.component_name} at visit count {break_point.visit_count}"
        return BreakpointException(message=msg, component=break_point.component_name, break_point=break_point)

    @property
    def inputs(self) -> dict[str, Any] | None:
        """
        Returns the current inputs of the pipeline at the breakpoint.
        """
        if not self.pipeline_snapshot:
            return None
        return self.pipeline_snapshot.pipeline_state.inputs

View on GitHub (pinned to e318778c9b)

Solutions

Pass either a pipeline_snapshot (PipelineSnapshot) or a break_point (Breakpoint) to the constructor
Use the classmethod BreakpointException.from_triggered_breakpoint(break_point) instead of __init__
If a snapshot file path is used, verify the file exists and load the snapshot before raising

Example fix

// before
raise BreakpointException(component=bp.component)

// after
raise BreakpointException.from_triggered_breakpoint(bp)  # or pass pipeline_snapshot=snapshot

Defensive patterns

Strategy: validation

Validate before calling

def make_breakpoint_exception(component, snapshot=None, break_point=None, path=None):
    if snapshot is None and break_point is None:
        raise ValueError("Provide pipeline_snapshot or break_point before constructing BreakpointException")
    return BreakpointException(component=component, pipeline_snapshot=snapshot, break_point=break_point, pipeline_snapshot_file_path=path)

Type guard

def can_build_breakpoint_exception(snapshot, break_point) -> bool:
    return snapshot is not None or break_point is not None

Try / catch

try:
    exc = BreakpointException(component=c)
except ValueError as e:
    logging.error("BreakpointException needs snapshot or break_point: %s", e)
    exc = BreakpointException.from_triggered_breakpoint(bp)

Prevention

Prefer BreakpointException.from_triggered_breakpoint over direct construction
Never build BreakpointException manually after swallowing the original one
Verify snapshot files exist before relying on pipeline_snapshot_file_path

When it happens

Trigger: Constructing BreakpointException(component=..., pipeline_snapshot=None, pipeline_snapshot_file_path=None, break_point=None) directly — typically from custom debugging/breakpoint tooling that forgot to attach either piece of state.

Common situations: Custom pipeline debugging harnesses building BreakpointException manually; a wrapper swallowing the original exception then re-raising a fresh BreakpointException without copying snapshot/break_point; loading a snapshot file path that was deleted and passing None for both.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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