deepset-ai/haystack · error · PipelineRuntimeError

PipelineRuntimeError.from_exception(component_name, instance

Error message

PipelineRuntimeError.from_exception(component_name, instance.__class__, error)

What it means

When a pipeline component's run() raises any exception that is not already a PipelineRuntimeError, Haystack wraps it in a PipelineRuntimeError carrying the component name and class, preserving the original exception via __cause__. The placeholder shown is the factory call used to build it.

Source

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

            try:
                component_output = instance.run(**inputs_copy)
            except BreakpointException as error:
                # Re-raise BreakpointException to preserve the original exception context
                # This is important when Agent components internally use Pipeline._run_component
                # and trigger breakpoints that need to bubble up to the main pipeline
                raise error

            # Any components that internally use Pipeline._run_component could raise a PipelineRuntimeError with
            # additional context (e.g. Agent raises an agent snapshot) so we re-raise here instead of wrapping it in
            # another PipelineRuntimeError

            except PipelineRuntimeError as runtime_error:
                raise runtime_error

            # Catch all other exceptions and wrap them in a PipelineRuntimeError
            except Exception as error:
                raise PipelineRuntimeError.from_exception(component_name, instance.__class__, error) from error

            component_visits[component_name] += 1

            if not isinstance(component_output, Mapping):
                raise PipelineRuntimeError.from_invalid_output(component_name, instance.__class__, component_output)

            _validate_component_output_keys(component_name, component, component_output)

            span.set_tag(_COMPONENT_VISITS, component_visits[component_name])
            span.set_content_tag(_COMPONENT_OUTPUT, component_output)

            return component_output

    @mark_deserialization_internal
    def run(  # noqa: PLR0915, PLR0912, C901
        self,
        data: dict[str, Any],
        include_outputs_from: set[str] | None = None,

View on GitHub (pinned to e318778c9b)

Solutions

1. Read the chained 'Caused by' stacktrace to find the original exception and failing component
2. Fix the root cause inside the named component (check the component_name in the message)
3. Wrap known-fragile component code in try/except or validate inputs before run()
4. Run the component in isolation with the same inputs to reproduce

Example fix

// before
class MyComp:
    def run(self, x):
        return {"out": 1 / x}
// after
class MyComp:
    def run(self, x):
        if x == 0:
            raise ValueError("x must be non-zero")
        return {"out": 1 / x}

# Reproduce the component in isolation before the pipeline run
out = my_component.run(**inputs)
assert isinstance(out, dict)

from haystack.core.errors import PipelineRuntimeError
try:
    result = pipeline.run({"q": query})
except PipelineRuntimeError as e:
    logger.error("Component %s failed", e)
    logger.debug("Root cause", exc_info=e.__cause__)

When it happens

Trigger: Any component raising inside Pipeline.run(): a ValueError in a custom component, an HTTP error inside aFetcher/Retriever, division by zero in user code, etc.

Common situations: Bugs in custom components, expired API keys causing requests to fail, bad input data to a component, dependency errors inside third-party components.

Related errors

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

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