{"record":{"id":"96e13f6f58d7513a","repo":"deepset-ai/haystack","slug":"pipelineruntimeerror-from-invalid-output-component","errorCode":null,"errorMessage":"PipelineRuntimeError.from_invalid_output(component_name, instance.__class__, component_output)","messagePattern":"PipelineRuntimeError\\.from_invalid_output\\(component_name, instance\\.__class__, component_output\\)","errorType":"exception","errorClass":"PipelineRuntimeError","httpStatus":null,"severity":"error","filePath":"haystack/core/pipeline/pipeline.py","lineNumber":190,"sourceCode":"                # This is important when Agent components internally use Pipeline._run_component\n                # and trigger breakpoints that need to bubble up to the main pipeline\n                raise error\n\n            # Any components that internally use Pipeline._run_component could raise a PipelineRuntimeError with\n            # additional context (e.g. Agent raises an agent snapshot) so we re-raise here instead of wrapping it in\n            # another PipelineRuntimeError\n\n            except PipelineRuntimeError as runtime_error:\n                raise runtime_error\n\n            # Catch all other exceptions and wrap them in a PipelineRuntimeError\n            except Exception as error:\n                raise PipelineRuntimeError.from_exception(component_name, instance.__class__, error) from error\n\n            component_visits[component_name] += 1\n\n            if not isinstance(component_output, Mapping):\n                raise PipelineRuntimeError.from_invalid_output(component_name, instance.__class__, component_output)\n\n            _validate_component_output_keys(component_name, component, component_output)\n\n            span.set_tag(_COMPONENT_VISITS, component_visits[component_name])\n            span.set_content_tag(_COMPONENT_OUTPUT, component_output)\n\n            return component_output\n\n    @mark_deserialization_internal\n    def run(  # noqa: PLR0915, PLR0912, C901\n        self,\n        data: dict[str, Any],\n        include_outputs_from: set[str] | None = None,\n        *,\n        break_point: Breakpoint | None = None,\n        pipeline_snapshot: PipelineSnapshot | None = None,\n        snapshot_callback: SnapshotCallback | None = None,\n    ) -> dict[str, Any]:","sourceCodeStart":172,"sourceCodeEnd":208,"githubUrl":"https://github.com/deepset-ai/haystack/blob/e318778c9bf60a1963e3b5f451359655dd696c30/haystack/core/pipeline/pipeline.py#L172-L208","documentation":"Haystack requires every component to return a Mapping (dict-like) output so results can be routed to other components. If a component's run() returns a non-mapping (list, string, None, object), PipelineRuntimeError.from_invalid_output is raised naming the component and its class.","triggerScenarios":"A custom component whose run() returns e.g. [\"a\", \"b\"], \"text\", or None instead of {\"output\": ...}; a mis-wrapped component from another framework.","commonSituations":"Hand-written components returning bare values, refactored components whose return type changed, third-party components not adapted to Haystack's Component contract.","solutions":["Make run() return a dict keyed by the component's declared output sockets, e.g. {\"documents\": docs}","Check the @component decorator output type declarations match the returned dict keys","Wrap third-party callables to convert their results into a dict"],"exampleFix":"// before\ndef run(self, docs):\n    return docs\n// after\ndef run(self, docs):\n    return {\"documents\": docs}","handlingStrategy":"validation","validationCode":"out = my_component.run(documents=docs)\nif not isinstance(out, Mapping):\n    raise TypeError(\"run() must return a dict keyed by output sockets\")","typeGuard":"from collections.abc import Mapping\ndef returns_mapping(out) -> bool:\n    return isinstance(out, Mapping)","tryCatchPattern":"from haystack.core.errors import PipelineRuntimeError\ntry:\n    result = pipeline.run(inputs)\nexcept PipelineRuntimeError as e:\n    if \"invalid output\" in str(e).lower():\n        logger.error(\"Fix component run() to return a dict: %s\", e)\n    else:\n        raise","preventionTips":["Always return a dict whose keys match the component's declared output sockets","Unit-test custom components' return types","Use the @component decorator's set_output_types to keep the contract explicit"],"tags":["python","pipeline","component-contract","type-validation"],"backgroundTag":"invalid-component-output","analyzedSha":"e318778c9bf60a1963e3b5f451359655dd696c30","analyzedAt":"2026-08-30T11:45:20.711Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}