{"record":{"id":"f003465997d8cbf6","repo":"docling-project/docling","slug":"failed-to-load-model-from-model-folder-exc","errorCode":null,"errorMessage":"Failed to load model from {model_folder}: {exc}","messagePattern":"Failed to load model from (.+?): (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/models/inference_engines/image_classification/transformers_engine.py","lineNumber":148,"sourceCode":"            self._model.eval()  # type: ignore[union-attr]\n\n            # Optionally compile model for better performance (model must be in eval mode first)\n            # Works for Python < 3.14 with any torch 2.x\n            # Works for Python >= 3.14 with torch >= 2.10\n            if self.options.compile_model:\n                if sys.version_info < (3, 14):\n                    self._model = torch.compile(self._model)  # type: ignore[arg-type,assignment]\n                    _log.debug(\"Model compiled with torch.compile()\")\n                elif version.parse(torch.__version__) >= version.parse(\"2.10\"):\n                    self._model = torch.compile(self._model)  # type: ignore[arg-type,assignment]\n                    _log.debug(\"Model compiled with torch.compile()\")\n                else:\n                    _log.warning(\n                        \"Model compilation requested but not available \"\n                        \"(requires Python < 3.14 or torch >= 2.10 for Python 3.14+)\"\n                    )\n        except Exception as exc:\n            raise RuntimeError(f\"Failed to load model from {model_folder}: {exc}\")\n\n        self._initialized = True\n        _log.info(\n            \"Transformers image-classification engine ready (device=%s, dtype=%s)\",\n            self._device,\n            self._model.dtype,  # type: ignore[union-attr]\n        )\n\n    def predict_batch(\n        self, input_batch: List[ImageClassificationEngineInput]\n    ) -> List[ImageClassificationEngineOutput]:\n        \"\"\"Run inference on a batch of inputs.\"\"\"\n        import torch\n\n        if not input_batch:\n            return []\n        if self._model is None or self._processor is None or self._device is None:\n            raise RuntimeError(\"Engine not initialized. Call initialize() first.\")","sourceCodeStart":130,"sourceCodeEnd":166,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/inference_engines/image_classification/transformers_engine.py#L130-L166","documentation":"A catch-all around the transformers model-loading block: from_preprocessor_config/from_pretrained loading, device placement, dtype casting, or optional torch.compile raised. The original exception is chained, so the message includes the underlying cause. It almost always reflects an environment or artifact problem (missing files, bad revision, unsupported dtype/device), not a docling logic bug.","triggerScenarios":"TransformersImageClassificationEngine.initialize() when any step inside the try block raises: downloading/loading the HF model folder, moving to device, casting dtype, or torch.compile — wrapped as RuntimeError(f\"Failed to load model from {model_folder}: {exc}\").","commonSituations":"No network / blocked HuggingFace access while fetching the model; wrong or unavailable revision; corrupted cache; CUDA requested but unavailable; unsupported torch dtype for the model; torch.compile incompatibility with the installed torch/Python version.","solutions":["Read the chained cause (raise ... from exc) — the '{exc}' part names the real failure; fix that first.","Pre-download the model (huggingface-cli download <repo_id>) or point to a local folder to rule out network/cache issues.","Verify accelerator/device settings match the environment (CPU-only host must not request CUDA) and the dtype is supported by the installed torch.","Disable torch.compile in options if the failure mentions compile/dynamo, or upgrade torch."],"exampleFix":"# before: compile requested on unsupported combo\noptions.compilation = ...  # triggers torch.compile path\n\n# after\n# keep options defaults (no forced compile); ensure model folder/revision is valid\nengine.initialize()  # if it fails, inspect __cause__ for the root error","handlingStrategy":"try-catch","validationCode":"from huggingface_hub import snapshot_download\n\npath = snapshot_download(repo_id=repo_id, revision=revision)  # fails early with a clear HF error if unreachable\nassert (Path(path) / \"config.json\").exists(), \"model folder incomplete\"","typeGuard":null,"tryCatchPattern":"try:\n    engine.initialize()\nexcept RuntimeError as e:\n    cause = e.__cause__\n    if cause and (\"ConnectionError\" in type(cause).__name__ or \"OfflineModeIsEnabled\" in type(cause).__name__):\n        # transient/network: pre-download then retry once\n        snapshot_download(repo_id=repo_id, revision=revision)\n        engine.initialize()\n    else:\n        raise","preventionTips":["Always inspect e.__cause__ — the wrapped exception carries the real reason.","Pre-download models in Docker/build stages so runtime loading never needs network.","Validate device/dtype settings against the host (no CUDA request on CPU-only machines).","Keep torch/transformers versions aligned with the model's requirements."],"tags":["transformers","model-loading","huggingface","environment"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}