{"record":{"id":"da5166fb93505bfc","repo":"docling-project/docling","slug":"failed-to-convert-doc-hash-self-document-hash","errorCode":null,"errorMessage":"Failed to convert doc (hash={self.document_hash}, name={self.file.name}).","messagePattern":"Failed to convert doc \\(hash=(.+?), name=(.+?)\\)\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/backend/xml/uspto_backend.py","lineNumber":178,"sourceCode":"    @override\n    def supports_pagination(cls) -> bool:\n        return False\n\n    @override\n    def unload(self) -> None:\n        return\n\n    @classmethod\n    @override\n    def supported_formats(cls) -> set[InputFormat]:\n        return {InputFormat.XML_USPTO}\n\n    @override\n    def convert(self) -> DoclingDocument:\n        if self.parser is not None:\n            doc = self.parser.parse(self.patent_content)\n            if doc is None:\n                raise RuntimeError(\n                    f\"Failed to convert doc (hash={self.document_hash}, \"\n                    f\"name={self.file.name}).\"\n                )\n            doc.name = self.file.name or \"file\"\n            mime_type = (\n                \"text/plain\"\n                if isinstance(self.parser, PatentUsptoGrantAps)\n                else \"application/xml\"\n            )\n            doc.origin = DocumentOrigin(\n                mimetype=mime_type,\n                binary_hash=self.document_hash,\n                filename=self.file.name or \"file\",\n            )\n\n            return doc\n        else:\n            raise RuntimeError(","sourceCodeStart":160,"sourceCodeEnd":196,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/xml/uspto_backend.py#L160-L196","documentation":"During convert(), the USPTO parser ran but returned None, meaning it could not produce a DoclingDocument from the patent_content. The backend raises RuntimeError including the document hash and filename so the failing input can be identified in logs. Parse() returning None signals content-level failure (unrecognized structure), not an exception.","triggerScenarios":"Calling convert() on a PatentUsptoDocumentBackend whose parser matched a DOCTYPE (so parser is set) but whose body content the parser cannot handle — malformed, truncated, or a patent flavor/variant the parser doesn't cover.","commonSituations":"Truncated bulk USPTO downloads that keep the header but lose the body; mixed corpora where a non-patent XML got a patent DOCTYPE; parser coverage gaps on newer/older patent schema variants.","solutions":["Use the hash/name from the message to locate the exact input file and inspect it manually.","Validate the document is a complete, well-formed patent (opens in an XML editor, ends with closing root tag).","Re-fetch the document from the source dataset.","Catch RuntimeError around conversion in batch jobs and quarantine the file for manual review."],"exampleFix":"# before\nresult = converter.convert(patent_path)  # RuntimeError: Failed to convert doc\n\n# after\ntry:\n    result = converter.convert(patent_path)\nexcept RuntimeError as e:\n    logger.error(\"skipping unparseable patent %s: %s\", patent_path, e)\n    quarantine.append(patent_path)","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    doc = backend.convert()\nexcept RuntimeError as e:\n    if \"Failed to convert doc\" in str(e):\n        logger.error(\"USPTO parse returned None for %s; quarantining\", backend.file.name)\n        return None\n    raise","preventionTips":["Extract hash/name from the message to find the offending file in large corpora.","Verify patents are complete (closing root tag present) before batch runs.","Quarantine parse-None files for manual triage instead of aborting the batch."],"tags":["uspto","patents","conversion","runtime-error"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}