{"record":{"id":"bc043de6c660e1c3","repo":"docling-project/docling","slug":"xbrl-loaded-with-errors-model-errors","errorCode":null,"errorMessage":"XBRL loaded with errors: {model.errors}","messagePattern":"XBRL loaded with errors: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/backend/xml/xbrl_backend.py","lineNumber":176,"sourceCode":"                    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\n    @override\n    def supports_pagination(cls) -> bool:\n        return False\n","sourceCodeStart":158,"sourceCodeEnd":194,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/xml/xbrl_backend.py#L158-L194","documentation":"Raised when Arelle loads the document but records errors in model.errors (a list of Arelle validation/loading problems). This means the file is structurally an XBRL instance but Arelle encountered issues while resolving it — commonly missing taxonomy files, unreachable remote schemas, or DTS reference failures.","triggerScenarios":"Loading an instance that references taxonomies not present locally while the Web Cache cannot fetch them (offline environment, blocked URLs, dead taxonomy URLs); taxonomy packages not passed via taxonomyPackages; instances referencing custom extension taxonomies that are unavailable. model.errors is non-empty after cntlr.modelManager.load().","commonSituations":"Air-gapped or proxy-restricted environments where Arelle cannot download https://www.xbrl.org/... schemas; SEC/ESMA filings that reference issuer-specific extension taxonomies not shipped alongside the instance; first-time runs with an empty Arelle web cache and no network egress.","solutions":["Read the embedded {model.errors} list — it names the exact unresolved references or validation failures.","Provide the needed taxonomy packages via the backend's taxonomy package (zip_paths) mechanism so Arelle resolves them locally.","Ensure network access (or a populated Arelle web cache) for the taxonomy URLs the instance references.","Download the filing's complete package (instance + extension taxonomy together) instead of just the instance file."],"exampleFix":"// before\nconvert(Path('filing.xbrl'))  # offline, taxonomy URLs unreachable -> 'XBRL loaded with errors'\n\n// after\n# pass taxonomy packages alongside the instance\nconvert(Path('filing.xbrl'), taxonomy_packages=[Path('extension_taxonomy.zip')])","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    result = converter.convert(path, taxonomy_packages=pkgs)\nexcept DocumentLoadError as e:\n    cause = str(e.__cause__ or '')\n    if 'XBRL loaded with errors' in cause:\n        # cause embeds model.errors listing unresolved taxonomies\n        fetch_or_package_missing_taxonomies(cause)","preventionTips":["Ship taxonomy packages (zips) alongside instances instead of relying on Arelle's web cache.","Pre-populate the Arelle web cache in networked CI for the taxonomies you process.","Read the embedded model.errors list — it names exactly what failed to resolve."],"tags":["xbrl","network","taxonomy","docling"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}