docling-project/docling · error · DocumentLoadError

docling-parse could not load document {self.document_hash}.

Error message

docling-parse could not load document {self.document_hash}.

What it means

This is the minimal variant of the docling-parse load failure: DoclingParseDocumentBackend caught a RuntimeError while calling parser.load(), but the exception's message was empty after stripping, so no detail can be appended. It signals the same class of problem as the detailed variant (unreadable/corrupt PDF, failed password) — only the diagnostics are missing.

Source

Thrown at docling/backend/docling_parse_backend.py:303

                self._pdoc = pdfium.PdfDocument(self.path_or_stream, password=password)
            self.parser = DoclingPdfParser(loglevel="fatal")
            decode_config = _make_docling_parse_decode_config(
                enforce_same_font=self.options.enforce_same_font,
            )
            self.dp_doc = self.parser.load(
                path_or_stream=self.path_or_stream,
                password=password,
                decode_config=decode_config,
            )
        except RuntimeError as e:
            # pypdfium2 (PdfiumError) and docling-parse both signal unreadable
            # bytes by raising RuntimeError; tag it as a load failure.
            detail = str(e).strip()
            if detail:
                raise DocumentLoadError(
                    f"docling-parse could not load document {self.document_hash}: {detail}"
                ) from e
            raise DocumentLoadError(
                f"docling-parse could not load document {self.document_hash}."
            ) from e

        if self.dp_doc is None:
            raise DocumentLoadError(
                f"docling-parse could not load document {self.document_hash}."
            )

    def page_count(self) -> int:
        # return len(self._pdoc)  # To be replaced with docling-parse API

        len_1 = len(self._pdoc)
        assert self.dp_doc is not None
        len_2 = self.dp_doc.number_of_pages()

        if len_1 != len_2:
            _log.error(f"Inconsistent number of pages: {len_1}!={len_2}")

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Treat it exactly like the detailed load error: check the file opens with pypdfium2 and validate whether it is encrypted (pypdfium2.PdfDocument(...).is_encrypted, needs a password).
2. Supply PdfPipelineOptions.pdf_password if the file is encrypted.
3. Inspect the chained exception (e.__cause__) and its type for more context than the empty message.
4. Repair or re-acquire the file (qpdf --check / re-download) if it is corrupt.

Example fix

# before
result = conv.convert(Path('weird.pdf'))  # RuntimeError with empty message

# after
import pypdfium2 as pdfium
try:
    pdf = pdfium.PdfDocument('weird.pdf')
except Exception as e:
    raise RuntimeError(f'file unusable before docling: {e}') from e
result = conv.convert(Path('weird.pdf'))

import pypdfium2 as pdfium

def pdf_usable(path) -> bool:
    try:
        pdf = pdfium.PdfDocument(str(path))
        return not pdf.is_encrypted or bool(pdf.authenticate(""))
    except Exception:
        return False

from docling.exceptions import DocumentLoadError
try:
    result = conv.convert(path)
except DocumentLoadError as e:
    if not str(e).rsplit(":", 1)[-1].strip():  # no detail appended
        diagnose_with_pypdfium2_or_qpdf(path)  # e.__cause__ type is your only hint
    raise

When it happens

Trigger: parser.load() raises a bare RuntimeError('') or RuntimeError with whitespace-only text — typically from native docling-parse code paths that raise without a message on low-level parse failures.

Common situations: Same as the detailed load error: corrupt PDFs, encrypted PDFs without a password, non-PDF bytes routed to the PDF backend. The empty message just makes triage harder because there is no parser hint.

Related errors

• docling-parse could not load document {self.document_hash}:
• CsvDocumentBackend could not load document with hash {self.d
• ThreadedDoclingParseDocumentBackend only supports iter_pages
• Could not initialize the EBCDIC backend for file with hash {
• Could not initialize MD backend for file with hash {self.doc

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