deepset-ai/haystack · warning · BreakpointException

BreakpointException.from_triggered_breakpoint(break_point=br

Error message

BreakpointException.from_triggered_breakpoint(break_point=break_point)

What it means

BreakpointException is raised in _run_component_async (pipeline.py:568) just before a component executes when the supplied Breakpoint matches the component about to run and its current visit count. It is Haystack's mechanism for interrupting a pipeline right before a specific component invocation so a snapshot can be taken. It is expected control flow for breakpoint-based debugging/human-in-the-loop flows, not corruption.

Source

Thrown at haystack/core/pipeline/pipeline.py:568

        """
        Executes a single component asynchronously.

        If the component supports async execution, it is awaited directly as it will run async;
        otherwise the component is offloaded to executor.

        The method also updates the `visits` count of the component, writes outputs to `inputs_state`,
        and returns pruned outputs that get stored in `pipeline_outputs`.

        :param component_name: The name of the component.
        :param component_inputs: Inputs for the component.
        :returns: Outputs from the component that can be yielded from run_async_generator.
        """
        if (
            isinstance(break_point, Breakpoint)
            and break_point.component_name == component_name
            and break_point.visit_count == component_visits[component_name]
        ):
            raise BreakpointException.from_triggered_breakpoint(break_point=break_point)

        instance: Component = component["instance"]

        with PipelineBase._create_component_span(
            component_name=component_name, instance=instance, inputs=component_inputs, parent_span=parent_span
        ) as span:
            # deepcopy inputs before passing to the tracer so that even if a tracer mutates them
            # the component always receives the original unmodified values
            component_inputs_copy = _deepcopy_with_exceptions(component_inputs)
            span.set_content_tag(_COMPONENT_INPUT, component_inputs)
            logger.info("Running component {component_name}", component_name=component_name)

            try:
                # For sync-only components, _run_component_async dispatches to a thread via asyncio.to_thread,
                # which copies the current contextvars context — preserving e.g. the active tracing span.
                outputs = await _execute_component_async(instance, **component_inputs_copy)
            except Exception as error:
                raise PipelineRuntimeError.from_exception(component_name, instance.__class__, error) from error

View on GitHub (pinned to e318778c9b)

Solutions

1. Catch BreakpointException and use its pipeline_snapshot to inspect state or persist and resume later.
2. If interruption was unintended, adjust visit_count (visits are 1-based per execution; cycles increment visits) or target a different component.
3. Remove the break_point argument for a normal uninterrupted run.

Example fix

from haystack.core.errors import BreakpointException
try:
    result = pipe.run(data, break_point=Breakpoint(component_name="llm", visit_count=1))
except BreakpointException as e:
    snapshot = e.pipeline_snapshot  # save/resume instead of crashing

from haystack.core.errors import BreakpointException
try:
    result = pipe.run(data, break_point=bp)
except BreakpointException as e:
    snapshot = e.pipeline_snapshot  # inspect, persist, and resume later

When it happens

Trigger: pipeline.run/breakpoint run where break_point.component_name equals the component about to execute and break_point.visit_count equals that component's current visit count; also hit on resume when the caller passes a breakpoint that still matches the pre-execution state.

Common situations: Human-in-the-loop interruption before an LLM or tool call; intentionally pausing before the Nth visit of a looping component; miscounting visits of components inside cycles so the breakpoint fires earlier than expected.

Related errors

• break_point {break_point} is not a registered component in t
• The provided break_point targets the same component and visi
• {type(self.chat_generator).__name__} does not accept tools p
• MarkdownHeaderSplitter only works with text documents but co
• Missing 'type' in component '{name}'

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