{"record":{"id":"82238235665e9a14","repo":"docling-project/docling","slug":"pypdfium-could-not-load-document-with-hash-self-d","errorCode":null,"errorMessage":"pypdfium could not load document with hash {self.document_hash}","messagePattern":"pypdfium could not load document with hash (.+?)","errorType":"exception","errorClass":"DocumentLoadError","httpStatus":null,"severity":"error","filePath":"docling/backend/pypdfium2_backend.py","lineNumber":427,"sourceCode":"class PyPdfiumDocumentBackend(ManagedPdfiumDocumentBackend):\n    def __init__(\n        self,\n        in_doc: \"InputDocument\",\n        path_or_stream: Union[BytesIO, Path],\n        options: Optional[PdfBackendOptions] = None,\n    ):\n        if options is None:\n            options = PdfBackendOptions()\n        super().__init__(in_doc, path_or_stream, options)\n\n        password = (\n            self.options.password.get_secret_value() if self.options.password else None\n        )\n        try:\n            with pypdfium2_lock:\n                self._pdoc = pdfium.PdfDocument(self.path_or_stream, password=password)\n        except PdfiumError as e:\n            raise DocumentLoadError(\n                f\"pypdfium could not load document with hash {self.document_hash}\"\n            ) from e\n\n    def page_count(self) -> int:\n        with pypdfium2_lock:\n            return len(self._pdoc)\n\n    def load_page(self, page_no: int) -> PyPdfiumPageBackend:\n        with pypdfium2_lock:\n            return PyPdfiumPageBackend(self._pdoc, self.document_hash, page_no)\n\n    def is_valid(self) -> bool:\n        return self.page_count() > 0\n\n    def get_document_outline(self) -> list[_PdfOutlineItem]:\n        \"\"\"Extract the PDF outline from the pypdfium2 document (title, depth, page, position).\"\"\"\n        if self._pdoc is None:\n            return []","sourceCodeStart":409,"sourceCodeEnd":445,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/pypdfium2_backend.py#L409-L445","documentation":"DocumentLoadError raised by the pypdfium2 backend constructor when pdfium.PdfDocument() raises PdfiumError for the given path/stream (including a failed password attempt via options.password). The original PdfiumError is chained; the message carries document_hash for correlation.","triggerScenarios":"Converting a corrupted or password-protected PDF without the correct PdfBackendOptions.password; empty or truncated PDF bytes; a file that is not a PDF at all. pypdfium2_lock serializes the call, then the except converts PdfiumError to DocumentLoadError.","commonSituations":"Scanned PDFs from scanners that produce slightly malformed files, encrypted PDFs from banks/HR, downloads interrupted mid-stream, and PDFs served with HTML error pages saved as .pdf.","solutions":["If the PDF is encrypted, pass the password: PdfBackendOptions(password=SecretStr('...')) on the format option (e.g. InputFormat.PDF options pipeline).","Validate the header first: the first bytes should be '%PDF-'; re-download truncated files.","Try repairing with qpdf --decrypt or ghostscript, then retry.","Fall back to the docling-parse PDF backend (pdf_backend) if pypdfium2 cannot parse a specific file."],"exampleFix":"# before\nres = converter.convert(Path('locked.pdf'))  # DocumentLoadError: pypdfium could not load\n\n# after\nfrom docling.datamodel.pipeline_options import PdfPipelineOptions\nopts = PdfPipelineOptions()\nfrom docling.datamodel.settings import PdfBackendOptions  # password lives on backend options\npipeline_options = PdfPipelineOptions(pdf_backend_options=None)\n# simplest: set format options password\nconv = DocumentConverter(\n    format_options={InputFormat.PDF: PdfFormatOptions(pipeline_options=opts)}\n)","handlingStrategy":"try-catch","validationCode":"with open(path, 'rb') as f:\n    header = f.read(5)\nif header != b'%PDF-':\n    raise ValueError('file is not a PDF')","typeGuard":null,"tryCatchPattern":"from docling.exceptions import DocumentLoadError\ntry:\n    result = converter.convert(path)\nexcept DocumentLoadError as e:\n    cause = e.__cause__\n    if 'password' in str(cause).lower():\n        result = converter.convert_with_password(path, pw)\n    else:\n        raise","preventionTips":["Check the %PDF- header at ingest","Pass PdfBackendOptions(password=SecretStr(...)) for encrypted files","Keep qpdf/ghostscript repair as a pre-processing fallback","Compare DocumentLoadError.__cause__ to distinguish encryption from corruption"],"tags":["pdf","pypdfium2","encrypted","load-failure"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}