docling-project/docling · error · ConversionError

Extraction failed for: {ext_res.input.file} with status: {ex

Error message

Extraction failed for: {ext_res.input.file} with status: {ext_res.status.value}.{error_details}

What it means

ConversionError raised by DocumentExtractor.extract() when raises_on_error=True and at least one ExtractionResult came back with a status other than SUCCESS/PARTIAL_SUCCESS. The message aggregates the per-result error_message entries so the underlying cause (model failure, backend error) is visible.

Source

Thrown at docling/document_extractor.py:183

            path_or_stream_iterator=source, limits=limits, headers=headers
        )

        ext_res_iter = self._extract(
            conv_input, raises_on_error=raises_on_error, template=template
        )

        had_result = False
        for ext_res in ext_res_iter:
            had_result = True
            if raises_on_error and ext_res.status not in {
                ConversionStatus.SUCCESS,
                ConversionStatus.PARTIAL_SUCCESS,
            }:
                error_details = ""
                if ext_res.errors:
                    error_messages = [err.error_message for err in ext_res.errors]
                    error_details = f" Errors: {'; '.join(error_messages)}"
                raise ConversionError(
                    f"Extraction failed for: {ext_res.input.file} with status: {ext_res.status.value}.{error_details}"
                )
            else:
                yield ext_res

        if not had_result and raises_on_error:
            raise ConversionError(
                "Extraction failed because the provided file has no recognizable format or it wasn't in the list of allowed formats."
            )

    # --------------------------- Internal engine ------------------------------

    def _extract(
        self,
        conv_input: _DocumentConversionInput,
        raises_on_error: bool,
        template: ExtractionTemplateType,
    ) -> Iterator[ExtractionResult]:

View on GitHub (pinned to 61d76f1ff3)

Solutions

Read the appended 'Errors: ...' details in the message; they identify the actual failing stage (backend vs model).
Call extract(..., raises_on_error=False) and handle failures per result by checking ext_res.status and ext_res.errors.
Fix the root cause reported in error_details (e.g. free GPU memory, repair the input file, install model artifacts).

Example fix

# before
results = extractor.extract(files)  # raises on first failed doc, aborts batch

# after
results = extractor.extract(files, raises_on_error=False)
for res in results:
    if res.status not in (ConversionStatus.SUCCESS, ConversionStatus.PARTIAL_SUCCESS):
        print('failed:', res.input.file, [e.error_message for e in res.errors])

Defensive patterns

Strategy: try-catch

Try / catch

from docling.datamodel.base_models import ConversionError
try:
    results = list(extractor.extract(files))
except ConversionError as e:
    log.error('extraction failed: %s', e)  # message includes per-result Errors: details
    results = list(extractor.extract(files, raises_on_error=False))

Prevention

Use raises_on_error=False for batch jobs and check result.status / result.errors per document.
Log ext_res.errors messages to identify the failing backend or model early.

When it happens

Trigger: extractor.extract(files, raises_on_error=True) (the default) where the pipeline executes but the result status is FAILURE, with details appended from result.errors.

Common situations: VLM extraction model fails to load or times out mid-run; a corrupted or password-protected PDF produces backend errors; OOM or GPU errors during batch extraction with raises_on_error left at default.

Related errors

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