docling-project/docling · error · ConversionError

Conversion failed for: {conv_res.input.file} with status: {c

Error message

Conversion failed for: {conv_res.input.file} with status: {conv_res.status.value}.{error_details}

What it means

After a conversion run, if raises_on_error is true and the result status is neither SUCCESS nor PARTIAL_SUCCESS, DocumentConverter raises ConversionError embedding the input file, the status value, and the joined per-error messages. The original exception from input construction is chained via `from get_input_rejection_cause(conv_res.input)` (issue #1920), so e.g. an encrypted PDF surfaces the underlying PdfiumError through __cause__.

Source

Thrown at docling/document_converter.py:581

        )
        conv_res_iter = self._convert(conv_input, raises_on_error=raises_on_error)

        had_result = False
        for conv_res in conv_res_iter:
            had_result = True
            if raises_on_error and conv_res.status not in {
                ConversionStatus.SUCCESS,
                ConversionStatus.PARTIAL_SUCCESS,
            }:
                error_details = ""
                if conv_res.errors:
                    error_messages = [err.error_message for err in conv_res.errors]
                    error_details = f" Errors: {'; '.join(error_messages)}"
                # Chain the underlying exception (when one was captured during
                # input construction) so callers can classify failures via
                # ``__cause__`` — e.g. an encrypted PDF surfaces the original
                # ``PdfiumError``. See issue #1920.
                raise ConversionError(
                    f"Conversion failed for: {conv_res.input.file} with status: "
                    f"{conv_res.status.value}.{error_details}"
                ) from get_input_rejection_cause(conv_res.input)
            else:
                yield conv_res

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

    @validate_call(config=ConfigDict(strict=True))
    def convert_string(
        self,
        content: str,
        format: InputFormat,
        name: Optional[str] = None,

View on GitHub (pinned to 61d76f1ff3)

Solutions

Read conv_res-equivalent details from the message and inspect the chained __cause__ to classify the real failure (e.g. PdfiumError for encrypted PDFs).
For batches, run convert_all(..., raises_on_error=False) and filter results by status, logging conv_res.errors for failures.
Fix the underlying document issue (decrypt the PDF, repair/redownload the file, install missing backend deps).

Example fix

# before
results = converter.convert_all(paths)  # dies on first bad file

# after
results = converter.convert_all(paths, raises_on_error=False)
for res in results:
    if res.status not in {ConversionStatus.SUCCESS, ConversionStatus.PARTIAL_SUCCESS}:
        log.warning("skipped %s: %s", res.input.file, [e.error_message for e in res.errors])

Defensive patterns

Strategy: try-catch

Try / catch

try:
    result = converter.convert(path)
except ConversionError as e:
    cause = e.__cause__  # e.g. PdfiumError for encrypted PDFs (issue #1920)
    if isinstance(cause, PdfiumError):
        mark_encrypted(path)
    else:
        log.error("conversion failed: %s", e)
    raise

Prevention

Use raises_on_error=False for batch jobs and inspect per-result status/errors.
Inspect the chained __cause__ to classify failures instead of string-matching messages.
Pre-screen for encrypted/corrupt PDFs before conversion.

When it happens

Trigger: converter.convert(path) / convert_all(...) with raises_on_error=True (the default) on a document that fails: corrupt/unsupported file, encrypted PDF, backend exceptions, or rejected input. Any status like FAILURE triggers the raise with the collected error_message list.

Common situations: Batch jobs that die on the first bad file instead of continuing; encrypted PDFs; partially downloaded or zero-byte files; format backends missing optional dependencies.

Related errors

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