docling-project/docling · error · DocumentLoadError

Could not initialize XBRL backend for file with hash {self.d

Error message

Could not initialize XBRL backend for file with hash {self.document_hash}.

What it means

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.

Source

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

                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:
        return False

    @override
    def unload(self):
        if self.model_xbrl:
            self.model_xbrl.close()

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Inspect the chained exception (catch DocumentLoadError and log .__cause__) to find the underlying failure — the wrapper message alone is generic.
2. Fix the root cause per the underlying error: bad file (errors 100-102), missing dependency, permissions, etc.
3. In batch pipelines, catch DocumentLoadError per file and continue, recording the hash for retry.
4. Confirm the arelle/XBRL extra is installed in your environment.

Example fix

// before
try:
    doc = converter.convert(f)
except DocumentLoadError as e:
    print(e)  # only the generic wrapper

// after
try:
    doc = converter.convert(f)
except DocumentLoadError as e:
    log.error('hash=%s cause=%r', e, e.__cause__)  # real reason
    failed.append(f)

try:
    result = converter.convert(path)
except DocumentLoadError as e:
    logger.error('file=%s hash-msg=%s cause=%r', path, e, e.__cause__)
    failed_files.append(path)  # continue batch; fix cause per errors 100-102

When it happens

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

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

Related errors

• Invalid or unreadable XBRL file
• Document is not an XBRL instance
• XBRL loaded with errors: {model.errors}
• Invalid document with hash {self.document_hash}
• The 'arelle-release' package is required to process XBRL doc

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