{"record":{"id":"071fb5a65dfb101c","repo":"docling-project/docling","slug":"docling-parse-could-not-load-document-self-docume","errorCode":null,"errorMessage":"docling-parse could not load document {self.document_hash}: {detail}","messagePattern":"docling-parse could not load document (.+?): (.+?)","errorType":"exception","errorClass":"DocumentLoadError","httpStatus":null,"severity":"error","filePath":"docling/backend/docling_parse_backend.py","lineNumber":300,"sourceCode":"        self.dp_doc: Optional[PdfDocument]\n        try:\n            with pypdfium2_lock:\n                self._pdoc = pdfium.PdfDocument(self.path_or_stream, password=password)\n            self.parser = DoclingPdfParser(loglevel=\"fatal\")\n            decode_config = _make_docling_parse_decode_config(\n                enforce_same_font=self.options.enforce_same_font,\n            )\n            self.dp_doc = self.parser.load(\n                path_or_stream=self.path_or_stream,\n                password=password,\n                decode_config=decode_config,\n            )\n        except RuntimeError as e:\n            # pypdfium2 (PdfiumError) and docling-parse both signal unreadable\n            # bytes by raising RuntimeError; tag it as a load failure.\n            detail = str(e).strip()\n            if detail:\n                raise DocumentLoadError(\n                    f\"docling-parse could not load document {self.document_hash}: {detail}\"\n                ) from e\n            raise DocumentLoadError(\n                f\"docling-parse could not load document {self.document_hash}.\"\n            ) from e\n\n        if self.dp_doc is None:\n            raise DocumentLoadError(\n                f\"docling-parse could not load document {self.document_hash}.\"\n            )\n\n    def page_count(self) -> int:\n        # return len(self._pdoc)  # To be replaced with docling-parse API\n\n        len_1 = len(self._pdoc)\n        assert self.dp_doc is not None\n        len_2 = self.dp_doc.number_of_pages()\n","sourceCodeStart":282,"sourceCodeEnd":318,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/docling_parse_backend.py#L282-L318","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Verify the file outside docling first: pypdfium2.PdfDocument('file.pdf') or qpdf --check file.pdf.","Re-download or repair the source document (qpdf --decrypt or the producer's re-export) for corrupt files.","In batch jobs, catch DocumentLoadError per file and quarantine failures instead of aborting the run."],"exampleFix":"# before\nresult = conv.convert(Path('locked.pdf'))  # encrypted, no password -> raises\n\n# after\nfrom docling.datamodel.pipeline_options import PdfPipelineOptions\nopts = PdfPipelineOptions()\nopts.pdf_password = 'secret'  # or retrieve from your secret store\nresult = conv.convert(Path('locked.pdf'), pipeline_options=opts)","handlingStrategy":"try-catch","validationCode":"import pypdfium2 as pdfium\nfrom pathlib import Path\n\ndef pdf_is_openable(path: Path, password: str | None = None) -> bool:\n    try:\n        pdf = pdfium.PdfDocument(str(path))\n    except Exception:\n        return False\n    if pdf.is_encrypted and not pdf.authenticate(password or \"\"):\n        return False\n    return True","typeGuard":null,"tryCatchPattern":"from docling.exceptions import DocumentLoadError\ntry:\n    result = conv.convert(path, pipeline_options=opts)\nexcept DocumentLoadError as e:\n    msg = str(e)\n    if \"password\" in msg.lower():\n        retry_with_password(path)  # fetch password, set opts.pdf_password\n    else:\n        quarantine(path, msg)","preventionTips":["Pre-check PDFs with pypdfium2 or qpdf --check before batch conversion.","Detect encrypted files up front and supply PdfPipelineOptions.pdf_password.","Catch DocumentLoadError per file so one bad PDF does not abort a batch."],"tags":["pdf","docling-parse","password","corrupt-file","document-load"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}