docling-project/docling · error · ValueError

The 'taxonomy' backend option must be a directory

Error message

The 'taxonomy' backend option must be a directory

What it means

You passed options.taxonomy to the XBRL backend, but the resolved path is not an existing directory, so it raises ValueError before copying taxonomy packages. The backend copies the taxonomy tree into a temp dir and collects its top-level .zip taxonomy packages, which only makes sense for a directory.

Source

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

        try:
            if (
                not self.options.enable_local_fetch
                and not self.options.enable_remote_fetch
            ):
                raise OperationNotAllowed(
                    "Fetching local or remote resources is only allowed when set"
                    " explicitly. Set 'options.enable_local_fetch=True' or"
                    " 'options.enable_remote_fetch=True'. Either one or the other"
                    " needs to be enabled to load taxonomies."
                )
            with TemporaryDirectory() as tmpdir:
                tmp_path: Path = Path(tmpdir)
                zip_paths: list[str] = []
                if self.options.taxonomy:
                    taxonomy: Path = self.options.taxonomy.resolve()
                    if not taxonomy.is_dir():
                        raise ValueError(
                            "The 'taxonomy' backend option must be a directory"
                        )
                    taxonomy_path = shutil.copytree(
                        taxonomy, tmp_path, dirs_exist_ok=True
                    )
                    zip_paths = [
                        str(item)
                        for item in taxonomy_path.iterdir()
                        if item.is_file()
                        and item.suffix.lower() == ".zip"
                        and zipfile.is_zipfile(item)
                    ]
                    if zip_paths:
                        _log.debug(
                            f"Files to be passed as taxonomy packages: {zip_paths}"
                        )
                if isinstance(path_or_stream, BytesIO):
                    instance_path: Path = tmp_path / "instance.xml"

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Point options.taxonomy at the directory that contains your taxonomy .zip packages, not at a zip file.
2. Check the path exists: Path(opts.taxonomy).resolve().is_dir() before constructing.
3. Fix relative paths by absolutizing them against a known base.
4. Omit options.taxonomy and use enable_remote_fetch=True if you want standard taxonomies fetched.

Example fix

# before
opts = XBRLBackendOptions(enable_local_fetch=True, taxonomy=Path("taxo/efx.zip"))

# after
# taxonomy must be a directory containing the zips
opts = XBRLBackendOptions(enable_local_fetch=True, taxonomy=Path("taxo"))  # taxo/efx.zip inside

from pathlib import Path

def taxonomy_option_ok(taxonomy: Path | None) -> bool:
    return taxonomy is None or taxonomy.resolve().is_dir()

try:
    backend = XBRLBackend(in_doc, src, opts)
except ValueError as e:
    if "must be a directory" in str(e):
        raise ValueError("options.taxonomy must point to the directory containing taxonomy zips") from e
    raise

When it happens

Trigger: XBRLBackendOptions(taxonomy=...) where taxonomy points to a .zip file, a non-existent path, or a regular file instead of a directory; the is_dir() check inside the __init__ try block fails.

Common situations: Users assuming taxonomy takes the zip file path directly; relative paths resolved against an unexpected cwd; taxonomy directory renamed/moved between environments.

Related errors

• Fetching local or remote resources is only allowed when set
• XBRL loaded with errors: {model.errors}
• Unknown EBCDIC codec {encoding!r}.
• The EBCDIC backend needs a layout: set either EbcdicBackendO
• Could not read the EBCDIC layout {self.options.layout_file}.

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