{"record":{"id":"38a8f60effeaa52b","repo":"immich-app/immich","slug":"model-file-not-found-model-path","errorCode":null,"errorMessage":"Model file not found: {model_path}","messagePattern":"Model file not found: (.+?)","errorType":"exception","errorClass":"FileNotFoundError","httpStatus":null,"severity":"error","filePath":"machine-learning/immich_ml/models/base.py","lineNumber":109,"sourceCode":"        if not rmtree.avoids_symlink_attacks:\n            raise RuntimeError(\"Attempted to clear cache, but rmtree is not safe on this platform\")\n\n        if self.cache_dir.is_dir():\n            log.info(f\"Cleared cache directory for model '{self.model_name}'.\")\n            rmtree(self.cache_dir)\n        else:\n            log.warning(\n                (\n                    f\"Encountered file instead of directory at cache path \"\n                    f\"for '{self.model_name}'. Removing file and replacing with a directory.\"\n                ),\n            )\n            self.cache_dir.unlink()\n        self.cache_dir.mkdir(parents=True, exist_ok=True)\n\n    def _make_session(self, model_path: Path) -> ModelSession:\n        if not model_path.is_file():\n            raise FileNotFoundError(f\"Model file not found: {model_path}\")\n\n        match model_path.suffix:\n            case \".armnn\":\n                session: ModelSession = AnnSession(model_path)\n            case \".onnx\":\n                session = OrtSession(model_path)\n            case \".rknn\":\n                session = rknn.RknnSession(model_path)\n            case _:\n                raise ValueError(f\"Unsupported model file type: {model_path.suffix}\")\n        return session\n\n    def model_path_for_format(self, model_format: ModelFormat) -> Path:\n        model_path_prefix = rknn.model_prefix if model_format == ModelFormat.RKNN else None\n        if model_path_prefix:\n            return self.model_dir / model_path_prefix / f\"model.{model_format}\"\n        return self.model_dir / f\"model.{model_format}\"\n","sourceCodeStart":91,"sourceCodeEnd":127,"githubUrl":"https://github.com/immich-app/immich/blob/199723261c6ffa897fec8ccdaea6359e39c37cc3/machine-learning/immich_ml/models/base.py#L91-L127","documentation":"Raised by InferenceModel._make_session when the resolved model_path does not point to a regular file. _make_session is invoked from _load() (called by load()), which runs after download() is supposed to have fetched the model from HuggingFace. The path is built by model_path_for_format() as cache_dir/<model_type>/model.<format> (plus an rknpu/<soc> prefix for RKNN), so the error means that expected artifact never materialized on disk.","triggerScenarios":"Calling model.load() (or predict(), which auto-loads) when snapshot_download() was skipped, interrupted, filtered out the needed file, or wrote to a different cache_dir than model_path points to. Also triggered when model_format does not match the files the HF repo actually ships, or after clear_cache() removed the directory but it was not re-downloaded.","commonSituations":"Wrong cache_folder / cache_dir mismatch between download and load; HuggingFace rate-limit or network failure leaving a partial download; setting model_format to ARMNN/RKNN while the repo only has ONNX weights (the ignore_patterns filter then excludes everything); read-only or full volume where the file could not be written; manual deletion of files under the cache directory.","solutions":["Inspect the value of model_path in the error and list its parent directory to see what (if anything) was actually downloaded.","Call model.clear_cache() then model.download() again to force a clean snapshot_download into the correct cache_dir.","Verify settings.cache_folder and the cache_dir passed to the model resolve to the same writable path used by snapshot_download.","Confirm model_format matches a file the HF repo ships (e.g. the ONNX variant) and that ignore_patterns for that format is not excluding it.","Check HuggingFace connectivity / token and available disk space, then retry load()."],"exampleFix":"# before\nmodel = InferenceModel('immich-app/X', model_format=ModelFormat.ARMNN)\nmodel.load()  # FileNotFoundError: cache only has ONNX\n\n# after\nmodel = InferenceModel('immich-app/X', model_format=ModelFormat.ONNX)\nmodel.clear_cache()\nmodel.download()\nmodel.load()","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\ndef ensure_model_file(path: Path) -> None:\n    if not path.is_file():\n        available = sorted(p.name for p in path.parent.glob('*')) if path.parent.exists() else []\n        raise FileNotFoundError(\n            f\"Expected model file {path} not found. Files in {path.parent}: {available}\"\n        )\n\n# call before model.load():\nensure_model_file(model.model_path)","typeGuard":"from pathlib import Path\n\ndef is_model_file_present(model) -> bool:\n    return isinstance(model.model_path, Path) and model.model_path.is_file()","tryCatchPattern":"try:\n    model.load()\nexcept FileNotFoundError as e:\n    log.error(\"Model artifact missing at %s; clearing cache and re-downloading\", model.model_path)\n    model.clear_cache()\n    model.download()\n    model.load()  # single retry, not a loop","preventionTips":["Always pair clear_cache() with a follow-up download() before relying on model_path.","In CI/startup, assert model.model_path.is_file() for every configured model before serving traffic.","Keep settings.cache_folder on a volume with enough free space and writable by the service user.","Match model_format to the files the HF repo ships so snapshot_download's ignore_patterns does not exclude them."],"tags":["model-loading","filesystem","huggingface","cache"],"backgroundTag":null,"analyzedSha":"199723261c6ffa897fec8ccdaea6359e39c37cc3","analyzedAt":"2026-08-12T04:54:27.085Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}