{"record":{"id":"0bae8dda9ebde110","repo":"docling-project/docling","slug":"invalid-document-with-hash-self-document-hash","errorCode":null,"errorMessage":"Invalid document with hash {self.document_hash}","messagePattern":"Invalid document with hash (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/backend/xml/xbrl_backend.py","lineNumber":252,"sourceCode":"            self._created_links.add(key)\n            self._links.append(\n                GraphLink(\n                    label=label,\n                    source_cell_id=src,\n                    target_cell_id=tgt,\n                )\n            )\n\n    @override\n    def convert(self) -> DoclingDocument:\n        \"\"\"Convert XBRL document to DoclingDocument using Arelle library.\n\n        This is a placeholder implementation that creates a basic document structure.\n        Full XBRL parsing using Arelle library can be implemented here.\n        \"\"\"\n        _log.debug(\"Starting XBRL instance conversion...\")\n        if not self.is_valid() or not self.model_xbrl:\n            raise RuntimeError(f\"Invalid document with hash {self.document_hash}\")\n\n        origin = DocumentOrigin(\n            filename=self.file.name or \"file\",\n            mimetype=\"application/xml\",\n            binary_hash=self.document_hash,\n        )\n        doc = DoclingDocument(name=self.file.stem or \"file\", origin=origin)\n        doc_name = doc.name\n\n        # Some metadata\n        doc_type: str = \"\"\n        doc_org: str = \"\"\n        doc_period: str = \"\"\n        for fact in self.model_xbrl.facts:\n            if fact.qname.localName == \"DocumentType\" and fact.value:\n                doc_type = fact.value\n            if fact.qname.localName == \"EntityRegistrantName\" and fact.value:\n                doc_org = fact.value","sourceCodeStart":234,"sourceCodeEnd":270,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/xml/xbrl_backend.py#L234-L270","documentation":"Raised by XbrlBackend.convert() when the backend was never successfully initialized — is_valid() is False or model_xbrl is None. It indicates convert() was called on a backend whose __init__ failed or was never run, which normally cannot happen through the public DocumentConverter API because failed backends are rejected during selection.","triggerScenarios":"Constructing XbrlBackend directly and calling convert() after a failed load; calling convert() on a backend instance whose initialization raised (leaving valid=False); programmatic reuse of a backend object across files.","commonSituations":"Code that instantiates backends manually (bypassing DocumentConverter's selection logic) or caches backend objects; test harnesses that construct the backend with stub files.","solutions":["Do not call convert() unless is_valid() returns True; check it first.","Use the public DocumentConverter API, which discards invalid backends and picks another one instead of letting you call convert() on them.","Create a fresh backend instance per document file.","If it happens via DocumentConverter, verify the file actually parses as XBRL (see errors 100-102)."],"exampleFix":"// before\nbackend = XbrlBackend(file, options)\ndoc = backend.convert()  # RuntimeError if init failed\n\n// after\nbackend = XbrlBackend(file, options)\nif backend.is_valid():\n    doc = backend.convert()","handlingStrategy":"type-guard","validationCode":"backend = XbrlBackend(file, options)\nif not backend.is_valid():\n    raise RuntimeError('backend init failed; do not call convert()')","typeGuard":"def backend_ready(b) -> bool:\n    return b.is_valid() and b.model_xbrl is not None","tryCatchPattern":"try:\n    doc = backend.convert()\nexcept RuntimeError as e:\n    if 'Invalid document' in str(e):\n        reinitialize_backend_with_valid_file()","preventionTips":["Prefer the public DocumentConverter API over manual backend construction.","Never reuse a backend object whose initialization raised.","Create one backend per document."],"tags":["xbrl","api-misuse","docling"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}