{"record":{"id":"f55eae2979094b7e","repo":"docling-project/docling","slug":"could-not-initialize-xbrl-backend-for-file-with-ha","errorCode":null,"errorMessage":"Could not initialize XBRL backend for file with hash {self.document_hash}.","messagePattern":"Could not initialize XBRL backend for file with hash (.+?)\\.","errorType":"exception","errorClass":"DocumentLoadError","httpStatus":null,"severity":"error","filePath":"docling/backend/xml/xbrl_backend.py","lineNumber":181,"sourceCode":"\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\n    @override\n    def supports_pagination(cls) -> bool:\n        return False\n\n    @override\n    def unload(self):\n        if self.model_xbrl:\n            self.model_xbrl.close()\n","sourceCodeStart":163,"sourceCodeEnd":199,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/xml/xbrl_backend.py#L163-L199","documentation":"This is the umbrella DocumentLoadError raised by XbrlBackend.__init__ when ANY exception occurs during Arelle initialization — the invalid-instance ValueErrors above, Arelle import errors, file I/O failures, or taxonomy resolution crashes. The original exception is attached via `from exc`, so the true cause is always in __cause__. The message includes the document hash to identify which file failed.","triggerScenarios":"Any exception inside the try block of XbrlBackend initialization: unreadable file, invalid XBRL (errors 100-102), missing arelle dependency, or an unexpected Arelle internal error. Caught by docling's conversion pipeline and reported as a failure for that document.","commonSituations":"Batch conversion jobs where one bad file aborts processing; environments where the arelle extra is not installed (pip install docling-arelle or similar); users seeing only this wrapper message and needing to inspect exc.__cause__ for the real reason.","solutions":["Inspect the chained exception (catch DocumentLoadError and log .__cause__) to find the underlying failure — the wrapper message alone is generic.","Fix the root cause per the underlying error: bad file (errors 100-102), missing dependency, permissions, etc.","In batch pipelines, catch DocumentLoadError per file and continue, recording the hash for retry.","Confirm the arelle/XBRL extra is installed in your environment."],"exampleFix":"// before\ntry:\n    doc = converter.convert(f)\nexcept DocumentLoadError as e:\n    print(e)  # only the generic wrapper\n\n// after\ntry:\n    doc = converter.convert(f)\nexcept DocumentLoadError as e:\n    log.error('hash=%s cause=%r', e, e.__cause__)  # real reason\n    failed.append(f)","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    result = converter.convert(path)\nexcept DocumentLoadError as e:\n    logger.error('file=%s hash-msg=%s cause=%r', path, e, e.__cause__)\n    failed_files.append(path)  # continue batch; fix cause per errors 100-102","preventionTips":["Always log e.__cause__ — the wrapper message is intentionally generic.","Catch DocumentLoadError per file in batch pipelines and continue.","Verify the arelle dependency is installed before processing XBRL."],"tags":["xbrl","error-handling","docling"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}