docling-project/docling · error · ValueError

XBRL loaded with errors: {model.errors}

Error message

XBRL loaded with errors: {model.errors}

What it means

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.

Source

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

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

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Read the embedded {model.errors} list — it names the exact unresolved references or validation failures.
2. Provide the needed taxonomy packages via the backend's taxonomy package (zip_paths) mechanism so Arelle resolves them locally.
3. Ensure network access (or a populated Arelle web cache) for the taxonomy URLs the instance references.
4. Download the filing's complete package (instance + extension taxonomy together) instead of just the instance file.

Example fix

// before
convert(Path('filing.xbrl'))  # offline, taxonomy URLs unreachable -> 'XBRL loaded with errors'

// after
# pass taxonomy packages alongside the instance
convert(Path('filing.xbrl'), taxonomy_packages=[Path('extension_taxonomy.zip')])

try:
    result = converter.convert(path, taxonomy_packages=pkgs)
except DocumentLoadError as e:
    cause = str(e.__cause__ or '')
    if 'XBRL loaded with errors' in cause:
        # cause embeds model.errors listing unresolved taxonomies
        fetch_or_package_missing_taxonomies(cause)

When it happens

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

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

Related errors

• Fetching local or remote resources is only allowed when set
• The 'taxonomy' backend option must be a directory
• Invalid or unreadable XBRL file
• Document is not an XBRL instance
• Could not initialize XBRL backend for file with hash {self.d

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