docling-project/docling · error · ValueError

Invalid or unreadable XBRL file

Error message

Invalid or unreadable XBRL file

What it means

Raised by the XBRL backend when Arelle's modelManager.load() returns something that is not a usable ModelXbrl (wrong type, falsy, or without a modelDocument). It means the file was accepted by the backend selector but Arelle could not parse it as an XBRL instance. The original ValueError is chained into a DocumentLoadError by the enclosing except block, so callers see 'Could not initialize XBRL backend for file with hash ...'.

Source

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

                    cntlr.webCache.workOffline = True
                    cntlr.modelManager.validateDisclosureSystem = False
                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

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Verify the file is a real XBRL instance document (root element like <xbrl> or <xbrli:xbrl>) by opening it in a text editor or validating with Arelle's GUI/CLI first.
2. If the file is a taxonomy, inline XBRL (iXbrl), or plain financial HTML, use the appropriate backend/converter instead of the XBRL backend.
3. Re-download or re-export the file to rule out truncation/corruption.
4. If the file should be valid, run `arelleCmdLine --file <file>` to see Arelle's own parse errors and fix accordingly.

Example fix

// before
converter = DocumentConverter()
result = converter.convert(Path('report.xbrl'))  # raises for non-XBRL content

// after
# validate the root element first
import xml.etree.ElementTree as ET
root = ET.parse('report.xbrl').getroot()
assert root.tag.endswith('xbrl'), 'not an XBRL instance'
result = converter.convert(Path('report.xbrl'))

import xml.etree.ElementTree as ET

def is_xbrl_instance(path) -> bool:
    try:
        root = ET.parse(path).getroot()
    except ET.ParseError:
        return False
    return root.tag.split('}')[-1] in ('xbrl', 'XBRL')

def looks_like_xbrl_instance(path: Path) -> bool:
    if path.suffix.lower() not in {'.xbrl', '.xml'}:
        return False
    return is_xbrl_instance(path)

try:
    result = converter.convert(path)
except DocumentLoadError as e:
    logger.error('XBRL load failed for %s: %r', path, e.__cause__)
    # skip or quarantine the file; do not retry unchanged

When it happens

Trigger: Passing a plain XML file, a malformed/truncated XBRL instance, an XBRL taxonomy (schema) file rather than an instance document, or a file whose XML is well-formed but not XBRL to the XbrlBackend. The check `not isinstance(model, ModelXbrl) or not model or not model.modelDocument` fires after cntlr.modelManager.load() returns.

Common situations: Pointing docling at ixbrl or xbrl-labeled files exported from accounting tools that are actually HTML wrappers; downloading an .xbrl file that is actually a taxonomy package; files corrupted in transfer; uppercase/lowercase extension mismatches causing the xbrl backend to be selected for non-XBRL XML.

Related errors

• Document is not an XBRL instance
• 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/d3e43aeedf3a6e1e. Report an issue: GitHub.