{"record":{"id":"e409596c60abb1db","repo":"docling-project/docling","slug":"cannot-convert-doc-hash-self-document-hash-nam","errorCode":null,"errorMessage":"Cannot convert doc (hash={self.document_hash}, name={self.file.name}) because the backend failed to init.","messagePattern":"Cannot convert doc \\(hash=(.+?), name=(.+?)\\) because the backend failed to init\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/backend/xml/uspto_backend.py","lineNumber":196,"sourceCode":"                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(\n                f\"Cannot convert doc (hash={self.document_hash}, \"\n                f\"name={self.file.name}) because the backend failed to init.\"\n            )\n\n\nclass PatentUspto(ABC):\n    \"\"\"Parser of patent documents from the US Patent Office.\"\"\"\n\n    @abstractmethod\n    def parse(self, patent_content: str) -> DoclingDocument | None:\n        \"\"\"Parse a USPTO patent.\n\n        Parameters:\n            patent_content: The content of a single patent in a USPTO file.\n\n        Returns:\n            The patent parsed as a docling document.\n        \"\"\"","sourceCodeStart":178,"sourceCodeEnd":214,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/xml/uspto_backend.py#L178-L214","documentation":"convert() was called while self.parser is None — the backend never matched a '<!DOCTYPE' or 'PATN' line during init, so it does not know which patent parser to use. This happens when format detection accepted the file (e.g. forced InputFormat) but the content has no recognizable USPTO header. Raised as RuntimeError with hash and filename.","triggerScenarios":"Constructing the backend on content whose first lines contain neither '<!DOCTYPE' nor exactly 'PATN\\n' (note: __init__ sniffing requires the exact byte match), then calling convert() — e.g. a generic XML file routed to the USPTO backend, or a patent with a BOM/CRLF so the line comparison fails.","commonSituations":"Files with Windows CRLF line endings making 'PATN\\n' comparison miss; BOM before DOCTYPE; wrong InputFormat forced in pipeline options; non-patent XML misclassified.","solutions":["Check the file's first lines: it must start with <!DOCTYPE us-patent-...> or the exact line 'PATN' (LF).","Normalize line endings to LF and strip any BOM before converting.","Don't force InputFormat.XML_USPTO for non-patent files; let DocumentConverter detect the format.","Catch this RuntimeError in batch jobs and route the file to the generic XML backend."],"exampleFix":"# before\nresult = converter.convert(Path(\"patent.txt\"))  # CRLF file, PATN line not matched\n\n# after\ntext = Path(\"patent.txt\").read_text().lstrip(\"\\ufeff\").replace(\"\\r\\n\", \"\\n\")\nfrom io import BytesIO\nresult = converter.convert(BytesIO(text.encode(\"utf-8\")))","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\ndef has_uspto_header(path: Path) -> bool:\n    with open(path, encoding=\"utf-8\", errors=\"replace\") as f:\n        first = f.readline().rstrip(\"\\r\\n\")\n    return first.startswith(\"<!DOCTYPE\") or first == \"PATN\"","typeGuard":null,"tryCatchPattern":"try:\n    doc = backend.convert()\nexcept RuntimeError as e:\n    if \"failed to init\" in str(e):\n        raise ValueError(\"no USPTO DOCTYPE/PATN header found; wrong format?\") from e\n    raise","preventionTips":["Normalize CRLF to LF and strip BOM before feeding patent files.","Don't force InputFormat.XML_USPTO on generic XML; let format detection decide.","Check that the first line is exactly 'PATN' (no trailing spaces) for APS files."],"tags":["uspto","patents","doctype","format-detection","line-endings"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}