What causes "Pipeline {self.__class__.__name__} failed" in docling-project/docling?

Read the chained cause: except RuntimeError as e: inspect e.__cause__ — fix that underlying exception

docling-project/docling · error · RuntimeError

Pipeline {self.class.name} failed

Error message

Pipeline {self.__class__.__name__} failed

What it means

BasePipeline.execute wraps the whole build/enrich flow; if any stage raises and raises_on_error is True, the pipeline marks the result FAILURE and re-raises the original exception chained to RuntimeError('Pipeline <Name> failed'). With raises_on_error=False the error is instead recorded in conv_res.errors and the exception is swallowed. This error is therefore a wrapper — the real cause is always in __cause__.

Source

Thrown at docling/pipeline/base_pipeline.py:94

                conv_res = self._assemble_document(conv_res)
                # From this stage, all operations should rely only on conv_res.output
                conv_res = self._enrich_document(conv_res)
                conv_res.status = self._determine_status(conv_res)
                # A document that completed but recorded errors is not a clean
                # success: never report SUCCESS while conv_res.errors is non-empty.
                if conv_res.status == ConversionStatus.SUCCESS and conv_res.errors:
                    conv_res.status = ConversionStatus.PARTIAL_SUCCESS
        except Exception as e:
            conv_res.status = ConversionStatus.FAILURE
            if not raises_on_error:
                error_item = ErrorItem(
                    component_type=DoclingComponentType.PIPELINE,
                    module_name=self.__class__.__name__,
                    error_message=str(e),
                )
                conv_res.errors.append(error_item)
            else:
                raise RuntimeError(f"Pipeline {self.__class__.__name__} failed") from e
        finally:
            self._unload(conv_res)

        return conv_res

    @abstractmethod
    def _build_document(self, conv_res: ConversionResult) -> ConversionResult:
        pass

    def _assemble_document(self, conv_res: ConversionResult) -> ConversionResult:
        return conv_res

    def _enrich_document(self, conv_res: ConversionResult) -> ConversionResult:
        def _prepare_elements(
            conv_res: ConversionResult, model: GenericEnrichmentModel[Any]
        ) -> Iterable[NodeItem]:
            for doc_element, _level in conv_res.document.iterate_items():
                prepared_element = model.prepare_element(

View on GitHub (pinned to 61d76f1ff3)

Solutions

Read the chained cause: except RuntimeError as e: inspect e.__cause__ — fix that underlying exception
For batch robustness, convert with raises_on_error=False and check conv_res.status / conv_res.errors per document
Reproduce with logging enabled (DOCLING_LOG_LEVEL=DEBUG) to identify the failing stage before the wrap

Example fix

# before
conv_res = converter.convert(doc)  # raises RuntimeError('Pipeline StandardPdfPipeline failed')

# after
from docling.datamodel.base_models import ConversionStatus
conv_res = converter.convert(doc)
if conv_res.status != ConversionStatus.SUCCESS:
    for err in conv_res.errors:
        print(err.module_name, err.error_message)

Defensive patterns

Strategy: try-catch

Try / catch

try:
    conv_res = converter.convert(doc)
except RuntimeError as e:
    if e.__cause__ is not None:
        log.error('underlying failure: %r', e.__cause__)
    # record and continue the batch
    results.append((doc, e.__cause__ or e))

Prevention

Use raises_on_error=False for batch workloads and branch on conv_res.status/errors instead
Always inspect __cause__ / full traceback — the wrapper message alone identifies no root cause
Log conv_res.errors entries when status is PARTIAL_SUCCESS to catch near-failures

When it happens

Trigger: DocumentConverter(..., raises_on_error=True).convert(doc) when any model in build_pipe/enrichment_pipe raises (model load failure, OCR crash, bad page data). The class name in the message tells you which pipeline (e.g. StandardPdfPipeline) but not which stage.

Common situations: Default CLI behaviour (raises_on_error=True); debugging a batch job that stops on the first bad document; users reading only the wrapper message and missing the 'The above exception was the direct cause' traceback section.

Related errors

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/62e0e08f14ed6aeb. Report an issue: GitHub.