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}: {detail}

What it means

DoclingParseDocumentBackend wraps every RuntimeError raised while loading the document through docling-parse (and pypdfium2, whose PdfiumError is also a RuntimeError) into this DocumentLoadError, appending the underlying message as detail. This is the primary 'cannot open this PDF' error: corrupt bytes, unsupported PDF constructs, or a wrong/missing password for an encrypted PDF all surface here with the parser's detail string included.

Source

Thrown at docling/backend/docling_parse_backend.py:300

        self.dp_doc: Optional[PdfDocument]
        try:
            with pypdfium2_lock:
                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()

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Read the detail suffix — 'password' diagnostics mean you must pass PdfPipelineOptions pdf_password (or the password is wrong); parse/structure errors mean damaged or non-PDF bytes.
2. Verify the file outside docling first: pypdfium2.PdfDocument('file.pdf') or qpdf --check file.pdf.
3. Re-download or repair the source document (qpdf --decrypt or the producer's re-export) for corrupt files.
4. In batch jobs, catch DocumentLoadError per file and quarantine failures instead of aborting the run.

Example fix

# before
result = conv.convert(Path('locked.pdf'))  # encrypted, no password -> raises

# after
from docling.datamodel.pipeline_options import PdfPipelineOptions
opts = PdfPipelineOptions()
opts.pdf_password = 'secret'  # or retrieve from your secret store
result = conv.convert(Path('locked.pdf'), pipeline_options=opts)

import pypdfium2 as pdfium
from pathlib import Path

def pdf_is_openable(path: Path, password: str | None = None) -> bool:
    try:
        pdf = pdfium.PdfDocument(str(path))
    except Exception:
        return False
    if pdf.is_encrypted and not pdf.authenticate(password or ""):
        return False
    return True

from docling.exceptions import DocumentLoadError
try:
    result = conv.convert(path, pipeline_options=opts)
except DocumentLoadError as e:
    msg = str(e)
    if "password" in msg.lower():
        retry_with_password(path)  # fetch password, set opts.pdf_password
    else:
        quarantine(path, msg)

When it happens

Trigger: Calling the PDF pipeline on: a truncated or corrupted PDF; a password-protected PDF where the wrong or no password was given (pdf_password in PdfPipelineOptions); a file that is not a PDF at all (magic bytes wrong) but was routed to the PDF backend.

Common situations: Interrupted downloads producing truncated PDFs; encrypted invoices/statements that need a password; batch folders where a .pdf-named image or HTML file sneaks in; old PDFs with constructs the parser rejects.

Related errors

• docling-parse could not load document {self.document_hash}.
• MsExcelDocumentBackend could not load document with hash {se
• MsPowerpointDocumentBackend could not load document with has
• CsvDocumentBackend could not load document with hash {self.d
• ThreadedDoclingParseDocumentBackend only supports iter_pages

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