{"record":{"id":"29a3ac8fc35ee3e1","repo":"docling-project/docling","slug":"document-is-not-an-xbrl-instance","errorCode":null,"errorMessage":"Document is not an XBRL instance","messagePattern":"Document is not an XBRL instance","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/backend/xml/xbrl_backend.py","lineNumber":174,"sourceCode":"                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\n    @override\n    def supports_pagination(cls) -> bool:","sourceCodeStart":156,"sourceCodeEnd":192,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/xml/xbrl_backend.py#L156-L192","documentation":"Raised when Arelle successfully loads a model document, but its type is not Type_INSTANCE — i.e., the file is a valid XBRL artifact (taxonomy schema, linkbase, etc.) rather than an instance document containing facts. The XBRL backend only converts instance documents, which are the ones that carry reported business data.","triggerScenarios":"Loading an XBRL taxonomy schema (.xsd), a label/reference linkbase (.xml), or a taxonomy package entry file through the XbrlBackend: model.modelDocument.type != Type_INSTANCE. The ValueError is then wrapped into DocumentLoadError by the enclosing handler.","commonSituations":"Users grab any file out of an SEC EDGAR or Companies House filing package; many of those files are taxonomies or linkbases, not the instance. Bulk-conversion pipelines that feed a whole directory of XBRL-related XML to docling hit this on the non-instance files.","solutions":["Identify the actual instance document in the filing (usually the largest .xbrl/.xml with <xbrl> root and context/units plus facts) and convert only that.","Skip or route non-instance XBRL files (schemas, linkbases) to a different backend or ignore them in batch jobs.","Pre-filter files by checking that the root element is an XBRL instance before invoking docling."],"exampleFix":"// before\nfor f in filing_dir.glob('*.xml'):\n    convert(f)  # raises 'Document is not an XBRL instance' on linkbases\n\n// after\nfor f in filing_dir.glob('*.xml'):\n    root = ET.parse(f).getroot()\n    if root.tag.split('}')[-1] == 'xbrl':\n        convert(f)","handlingStrategy":"validation","validationCode":"import xml.etree.ElementTree as ET\n\ndef is_xbrl_instance_doc(path) -> bool:\n    root = ET.parse(path).getroot()\n    local = root.tag.split('}')[-1]\n    return local == 'xbrl'  # excludes taxonomy schemas (.xsd) and linkbases","typeGuard":null,"tryCatchPattern":"try:\n    result = converter.convert(path)\nexcept DocumentLoadError as e:\n    if 'not an XBRL instance' in str(e.__cause__ or ''):\n        skip_non_instance(path)  # taxonomy/linkbase: expected in filing packages\n    else:\n        raise","preventionTips":["Convert only the instance document from filing packages, not every XML file.","Learn the filing structure: instance vs schema (.xsd) vs linkbase.","Log and skip expected non-instance files in batch pipelines."],"tags":["xbrl","validation","docling"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}