{"record":{"id":"7e125223a934adf1","repo":"docling-project/docling","slug":"the-taxonomy-backend-option-must-be-a-directory","errorCode":null,"errorMessage":"The 'taxonomy' backend option must be a directory","messagePattern":"The 'taxonomy' backend option must be a directory","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/backend/xml/xbrl_backend.py","lineNumber":125,"sourceCode":"\n        try:\n            if (\n                not self.options.enable_local_fetch\n                and not self.options.enable_remote_fetch\n            ):\n                raise OperationNotAllowed(\n                    \"Fetching local or remote resources is only allowed when set\"\n                    \" explicitly. Set 'options.enable_local_fetch=True' or\"\n                    \" 'options.enable_remote_fetch=True'. Either one or the other\"\n                    \" needs to be enabled to load taxonomies.\"\n                )\n            with TemporaryDirectory() as tmpdir:\n                tmp_path: Path = Path(tmpdir)\n                zip_paths: list[str] = []\n                if self.options.taxonomy:\n                    taxonomy: Path = self.options.taxonomy.resolve()\n                    if not taxonomy.is_dir():\n                        raise ValueError(\n                            \"The 'taxonomy' backend option must be a directory\"\n                        )\n                    taxonomy_path = shutil.copytree(\n                        taxonomy, tmp_path, dirs_exist_ok=True\n                    )\n                    zip_paths = [\n                        str(item)\n                        for item in taxonomy_path.iterdir()\n                        if item.is_file()\n                        and item.suffix.lower() == \".zip\"\n                        and zipfile.is_zipfile(item)\n                    ]\n                    if zip_paths:\n                        _log.debug(\n                            f\"Files to be passed as taxonomy packages: {zip_paths}\"\n                        )\n                if isinstance(path_or_stream, BytesIO):\n                    instance_path: Path = tmp_path / \"instance.xml\"","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/xml/xbrl_backend.py#L107-L143","documentation":"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.","triggerScenarios":"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.","commonSituations":"Users assuming taxonomy takes the zip file path directly; relative paths resolved against an unexpected cwd; taxonomy directory renamed/moved between environments.","solutions":["Point options.taxonomy at the directory that contains your taxonomy .zip packages, not at a zip file.","Check the path exists: Path(opts.taxonomy).resolve().is_dir() before constructing.","Fix relative paths by absolutizing them against a known base.","Omit options.taxonomy and use enable_remote_fetch=True if you want standard taxonomies fetched."],"exampleFix":"# before\nopts = XBRLBackendOptions(enable_local_fetch=True, taxonomy=Path(\"taxo/efx.zip\"))\n\n# after\n# taxonomy must be a directory containing the zips\nopts = XBRLBackendOptions(enable_local_fetch=True, taxonomy=Path(\"taxo\"))  # taxo/efx.zip inside","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\ndef taxonomy_option_ok(taxonomy: Path | None) -> bool:\n    return taxonomy is None or taxonomy.resolve().is_dir()","typeGuard":null,"tryCatchPattern":"try:\n    backend = XBRLBackend(in_doc, src, opts)\nexcept ValueError as e:\n    if \"must be a directory\" in str(e):\n        raise ValueError(\"options.taxonomy must point to the directory containing taxonomy zips\") from e\n    raise","preventionTips":["Pass the directory containing taxonomy .zip packages, never a zip file path.","Resolve taxonomy paths absolutely before building options.","Assert is_dir() in tests that exercise XBRL options."],"tags":["xbrl","taxonomy","path-validation","configuration"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}