{"record":{"id":"c02ff027fddaa602","repo":"docling-project/docling","slug":"failed-to-load-model-from-model-folder-e","errorCode":null,"errorMessage":"Failed to load model from {model_folder}: {e}","messagePattern":"Failed to load model from (.+?): (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/models/inference_engines/object_detection/transformers_engine.py","lineNumber":172,"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 e:\n            raise RuntimeError(f\"Failed to load model from {model_folder}: {e}\")\n\n        self._initialized = True\n        _log.info(\n            f\"Transformers engine ready (device={self._device}, dtype={self._model.dtype})\"  # type: ignore[union-attr]\n        )\n\n    def predict_batch(\n        self, input_batch: List[ObjectDetectionEngineInput]\n    ) -> List[ObjectDetectionEngineOutput]:\n        \"\"\"Run inference on a batch of inputs.\n\n        Args:\n            input_batch: List of input images with metadata\n\n        Returns:\n            List of detection outputs\n        \"\"\"\n        import torch","sourceCodeStart":154,"sourceCodeEnd":190,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/inference_engines/object_detection/transformers_engine.py#L154-L190","documentation":"The Transformers engine wraps every exception thrown while loading the model/processor from the model folder into RuntimeError('Failed to load model from {model_folder}: {e}'). It is a wrapper: the root cause (corrupt weights, unsupported torch/transformers version, OOM, compile failure) is in the chained exception message.","triggerScenarios":"Any exception inside the big load block: from_pretrained on a corrupt/incomplete download, torch.compile being attempted on unsupported Python/torch combos (guarded above but other compile errors possible), safetensors/pickle load errors, CUDA init failures, out-of-memory.","commonSituations":"Interrupted HF downloads leaving partial weight shards; transformers/torch version incompatibility with the model architecture; GPU OOM at load time; artifacts_path folder truncated during copy to a server.","solutions":["Read the full chained traceback — the '{e}' suffix names the underlying loader error; fix that first.","If weights are corrupt/partial, delete the model folder in the cache/artifacts_path and re-download.","Pin compatible torch/transformers versions for the model (check the model card); for compile issues, disable the compile option in the engine options.","For OOM, choose a smaller device/dtype setting in accelerator options."],"exampleFix":"# before\nengine.initialize()  # raises generic 'Failed to load model from ...'\n\n# after\n# run with full traceback to see the cause:\n#   python -X dev app.py   (or inspect __cause__ in except)\n# then e.g. remove corrupt cache and retry:\n#   rm -rf ~/.cache/huggingface/hub/models--BioMedClIP--... && rerun","handlingStrategy":"try-catch","validationCode":"# fail fast on obviously broken artifacts before init\nweights = list(model_folder.glob('*.safetensors')) + list(model_folder.glob('*.bin'))\nassert weights, f\"no weight files found in {model_folder}\"","typeGuard":null,"tryCatchPattern":"try:\n    engine.initialize()\nexcept RuntimeError as e:\n    cause = e.__cause__ or e.__context__\n    log.error(\"Model load failed: %s | root cause: %s\", e, cause)\n    raise","preventionTips":["Always inspect __cause__ — the wrapper message alone is not actionable.","Re-download models on any checksum/partial-file suspicion.","Pin torch/transformers versions tested with the model; disable compile options when versions don't support it."],"tags":["transformers","model-loading","wrapper-exception","dependencies"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}