{"record":{"id":"26eb72dfafebde59","repo":"docling-project/docling","slug":"failed-to-load-image-processor-from-model-folder","errorCode":null,"errorMessage":"Failed to load image processor from {model_folder}: {exc}","messagePattern":"Failed to load image processor from (.+?): (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/models/inference_engines/common/hf_vision_base.py","lineNumber":89,"sourceCode":"            artifacts_path=self._artifacts_path,\n            download_fn=download_wrapper,\n        )\n\n    def _load_preprocessor(self, model_folder: Path) -> BaseImageProcessor:\n        \"\"\"Load HuggingFace image processor from model folder.\"\"\"\n        preprocessor_config = model_folder / \"preprocessor_config.json\"\n        if not preprocessor_config.exists():\n            raise FileNotFoundError(\n                f\"Image processor config not found: {preprocessor_config}\"\n            )\n\n        try:\n            from transformers import AutoImageProcessor\n\n            _log.debug(\"Loading image processor from %s\", model_folder)\n            return AutoImageProcessor.from_pretrained(str(model_folder))\n        except Exception as exc:\n            raise RuntimeError(\n                f\"Failed to load image processor from {model_folder}: {exc}\"\n            )\n\n    def _load_label_mapping(self, model_folder: Path) -> Dict[int, str]:\n        \"\"\"Load label mapping from HuggingFace model config.\"\"\"\n        try:\n            from transformers import AutoConfig\n\n            config = AutoConfig.from_pretrained(str(model_folder))\n            return {\n                int(label_id): label_name\n                for label_id, label_name in config.id2label.items()\n            }\n        except Exception as exc:\n            raise RuntimeError(\n                f\"Failed to load label mapping from model config at {model_folder}: {exc}\"\n            )\n","sourceCodeStart":71,"sourceCodeEnd":107,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/inference_engines/common/hf_vision_base.py#L71-L107","documentation":"Raised as RuntimeError by HfVisionModelMixin._load_preprocessor wrapping any exception from AutoImageProcessor.from_pretrained on the model folder. The original error is embedded in the message; common causes are transformers version incompatibilities, corrupt config files, or missing processor dependencies.","triggerScenarios":"preprocessor_config.json exists but AutoImageProcessor.from_pretrained(model_folder) raises — unsupported processor_type in the installed transformers version, malformed JSON, or a processor class requiring an extra dependency.","commonSituations":"Downgraded/upgraded transformers so the processor class for the repo no longer exists; hand-edited or truncated preprocessor_config.json; model repo requiring newer feature-extractor APIs.","solutions":["Read the ': {exc}' tail of the message — it carries the underlying transformers error; fix that root cause.","Upgrade or pin transformers to the version documented for the model family used by this Docling release.","If the config file is corrupt, re-download the model artifacts from the HF repo."],"exampleFix":"# before: RuntimeError: Failed to load image processor ...: KeyError 'ImageProcessor'\n# pin a compatible transformers\n# uv add 'transformers==4.48.3'  # version required by this docling release","handlingStrategy":"try-catch","validationCode":"import json\nfrom pathlib import Path\ncfg = Path(model_folder) / 'preprocessor_config.json'\njson.loads(cfg.read_text())  # fail early on malformed config","typeGuard":null,"tryCatchPattern":"try:\n    model = MyVisionModel(...)\nexcept RuntimeError as e:\n    if 'Failed to load image processor' in str(e):\n        log.error('processor load failed: %s', e.__cause__ or e)\n        raise  # fix transformers version / artifacts, do not retry","preventionTips":["Pin transformers to the version range required by your Docling release.","Smoke-test model loading in CI with the exact dependency lockfile you deploy.","Keep the chained __cause__ in logs — it names the real transformers error."],"tags":["huggingface","transformers","model-loading","compatibility"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}