{"record":{"id":"d3e43aeedf3a6e1e","repo":"docling-project/docling","slug":"invalid-or-unreadable-xbrl-file","errorCode":null,"errorMessage":"Invalid or unreadable XBRL file","messagePattern":"Invalid or unreadable XBRL file","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/backend/xml/xbrl_backend.py","lineNumber":172,"sourceCode":"                    cntlr.webCache.workOffline = True\n                    cntlr.modelManager.validateDisclosureSystem = False\n                else:\n                    # TODO: parametrize the timeout?\n                    cntlr.webCache.timeout = _WEB_CACHE_TIMEOUT\n                    # TODO: custom set cntlr.webCache.cacheDir?\n                    _log.debug(\n                        f\"Web Cache for remote taxonomy is: {cntlr.webCache.cacheDir}\"\n                    )\n\n                model = cntlr.modelManager.load(\n                    str(instance_path), taxonomyPackages=zip_paths\n                )\n                if (\n                    not isinstance(model, ModelXbrl)\n                    or not model\n                    or not model.modelDocument\n                ):\n                    raise ValueError(\"Invalid or unreadable XBRL file\")\n                if model.modelDocument.type != Type.INSTANCE:\n                    raise ValueError(\"Document is not an XBRL instance\")\n                if model.errors:\n                    raise ValueError(f\"XBRL loaded with errors: {model.errors}\")\n\n            self.model_xbrl = model\n            self.valid = True\n        except Exception as exc:\n            raise DocumentLoadError(\n                \"Could not initialize XBRL backend for file with hash\"\n                f\" {self.document_hash}.\"\n            ) from exc\n\n    @override\n    def is_valid(self) -> bool:\n        return self.valid\n\n    @classmethod","sourceCodeStart":154,"sourceCodeEnd":190,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/xml/xbrl_backend.py#L154-L190","documentation":"Raised by the XBRL backend when Arelle's modelManager.load() returns something that is not a usable ModelXbrl (wrong type, falsy, or without a modelDocument). It means the file was accepted by the backend selector but Arelle could not parse it as an XBRL instance. The original ValueError is chained into a DocumentLoadError by the enclosing except block, so callers see 'Could not initialize XBRL backend for file with hash ...'.","triggerScenarios":"Passing a plain XML file, a malformed/truncated XBRL instance, an XBRL taxonomy (schema) file rather than an instance document, or a file whose XML is well-formed but not XBRL to the XbrlBackend. The check `not isinstance(model, ModelXbrl) or not model or not model.modelDocument` fires after cntlr.modelManager.load() returns.","commonSituations":"Pointing docling at ixbrl or xbrl-labeled files exported from accounting tools that are actually HTML wrappers; downloading an .xbrl file that is actually a taxonomy package; files corrupted in transfer; uppercase/lowercase extension mismatches causing the xbrl backend to be selected for non-XBRL XML.","solutions":["Verify the file is a real XBRL instance document (root element like <xbrl> or <xbrli:xbrl>) by opening it in a text editor or validating with Arelle's GUI/CLI first.","If the file is a taxonomy, inline XBRL (iXbrl), or plain financial HTML, use the appropriate backend/converter instead of the XBRL backend.","Re-download or re-export the file to rule out truncation/corruption.","If the file should be valid, run `arelleCmdLine --file <file>` to see Arelle's own parse errors and fix accordingly."],"exampleFix":"// before\nconverter = DocumentConverter()\nresult = converter.convert(Path('report.xbrl'))  # raises for non-XBRL content\n\n// after\n# validate the root element first\nimport xml.etree.ElementTree as ET\nroot = ET.parse('report.xbrl').getroot()\nassert root.tag.endswith('xbrl'), 'not an XBRL instance'\nresult = converter.convert(Path('report.xbrl'))","handlingStrategy":"validation","validationCode":"import xml.etree.ElementTree as ET\n\ndef is_xbrl_instance(path) -> bool:\n    try:\n        root = ET.parse(path).getroot()\n    except ET.ParseError:\n        return False\n    return root.tag.split('}')[-1] in ('xbrl', 'XBRL')","typeGuard":"def looks_like_xbrl_instance(path: Path) -> bool:\n    if path.suffix.lower() not in {'.xbrl', '.xml'}:\n        return False\n    return is_xbrl_instance(path)","tryCatchPattern":"try:\n    result = converter.convert(path)\nexcept DocumentLoadError as e:\n    logger.error('XBRL load failed for %s: %r', path, e.__cause__)\n    # skip or quarantine the file; do not retry unchanged","preventionTips":["Pre-filter XML files by root element before feeding them to the XBRL backend.","In batch jobs, validate each file and route non-XBRL XML to other backends.","Keep the arelle extra installed in environments that process XBRL."],"tags":["xbrl","validation","parsing","docling"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}