docling-project/docling · error · ValueError

Document is not an XBRL instance

Error message

Document is not an XBRL instance

What it means

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.

Source

Thrown at docling/backend/xml/xbrl_backend.py:174

                else:
                    # TODO: parametrize the timeout?
                    cntlr.webCache.timeout = _WEB_CACHE_TIMEOUT
                    # TODO: custom set cntlr.webCache.cacheDir?
                    _log.debug(
                        f"Web Cache for remote taxonomy is: {cntlr.webCache.cacheDir}"
                    )

                model = cntlr.modelManager.load(
                    str(instance_path), taxonomyPackages=zip_paths
                )
                if (
                    not isinstance(model, ModelXbrl)
                    or not model
                    or not model.modelDocument
                ):
                    raise ValueError("Invalid or unreadable XBRL file")
                if model.modelDocument.type != Type.INSTANCE:
                    raise ValueError("Document is not an XBRL instance")
                if model.errors:
                    raise ValueError(f"XBRL loaded with errors: {model.errors}")

            self.model_xbrl = model
            self.valid = True
        except Exception as exc:
            raise DocumentLoadError(
                "Could not initialize XBRL backend for file with hash"
                f" {self.document_hash}."
            ) from exc

    @override
    def is_valid(self) -> bool:
        return self.valid

    @classmethod
    @override
    def supports_pagination(cls) -> bool:

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. 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.
2. Skip or route non-instance XBRL files (schemas, linkbases) to a different backend or ignore them in batch jobs.
3. Pre-filter files by checking that the root element is an XBRL instance before invoking docling.

Example fix

// before
for f in filing_dir.glob('*.xml'):
    convert(f)  # raises 'Document is not an XBRL instance' on linkbases

// after
for f in filing_dir.glob('*.xml'):
    root = ET.parse(f).getroot()
    if root.tag.split('}')[-1] == 'xbrl':
        convert(f)

import xml.etree.ElementTree as ET

def is_xbrl_instance_doc(path) -> bool:
    root = ET.parse(path).getroot()
    local = root.tag.split('}')[-1]
    return local == 'xbrl'  # excludes taxonomy schemas (.xsd) and linkbases

try:
    result = converter.convert(path)
except DocumentLoadError as e:
    if 'not an XBRL instance' in str(e.__cause__ or ''):
        skip_non_instance(path)  # taxonomy/linkbase: expected in filing packages
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Invalid or unreadable XBRL file
• XBRL loaded with errors: {model.errors}
• Could not initialize XBRL backend for file with hash {self.d
• Invalid document with hash {self.document_hash}
• Cannot convert Box Note with hash {self.document_hash}: no '

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/29a3ac8fc35ee3e1. Report an issue: GitHub.