{"record":{"id":"208b503b334e63fc","repo":"deepinsight/insightface","slug":"failed-to-download-model-from-modelscope-e","errorCode":null,"errorMessage":"Failed to download model from ModelScope: {e}","messagePattern":"Failed to download model from ModelScope: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"cpp-package/inspireface/python/inspireface/modules/utils/resource.py","lineNumber":139,"sourceCode":"        \n        try:\n            # Download specific model file from ModelScope\n            cache_dir = snapshot_download(\n                model_id=self.modelscope_model_id,\n                cache_dir=str(self.modelscope_cache_dir),\n                allow_file_pattern=[model_name]  # Only download the specific model file\n            )\n            \n            model_file_path = Path(cache_dir) / model_name\n            \n            if not model_file_path.exists():\n                raise FileNotFoundError(f\"Model file '{model_name}' not found in downloaded repository\")\n                \n            print(f\"ModelScope download completed: {model_file_path}\")\n            return str(model_file_path)\n            \n        except Exception as e:\n            raise RuntimeError(f\"Failed to download model from ModelScope: {e}\")\n\n    def get_model(self, name: str, re_download: bool = False, ignore_verification: bool = False) -> str:\n        \"\"\"\n        Get model path. Download if not exists or re_download is True.\n        \n        Args:\n            name: Model name\n            re_download: Force re-download if True\n            ignore_verification: Skip model hash verification if True\n            \n        Returns:\n            str: Full path to model file\n        \"\"\"\n        # Check global OSS setting first, then instance setting\n        use_oss = USE_OSS_DOWNLOAD\n        use_modelscope_actual = self.use_modelscope and not use_oss\n        \n        # Use ModelScope download if enabled and OSS is not forced","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/cpp-package/inspireface/python/inspireface/modules/utils/resource.py#L121-L157","documentation":"_download_from_modelscope wraps the whole snapshot_download + file-check block in try/except and re-raises any failure as RuntimeError('Failed to download model from ModelScope: {e}'). The {e} text carries the true cause — network errors, auth problems, or modelscope API failures.","triggerScenarios":"Any exception from modelscope.snapshot_download (HTTP/network failure, rate limit, invalid repo id, disk full) or from Path operations while resolving the cached file, during get_model in ModelScope mode.","commonSituations":"Corporate proxies/firewalls blocking modelscope.cn or CDN; flaky CI networks; expired/invalid modelscope credentials for gated repos; full disk in the cache directory.","solutions":["Read the embedded {e} message to identify network vs auth vs disk cause","Retry with a stable network / configure HTTPS_PROXY if behind a corporate proxy","Pre-download the model (or vendor it into the image) and place it in the models dir so no runtime download occurs","If modelscope is flaky, switch to OSS: inspireface.use_oss_download(True)"],"exampleFix":"# before\npath = resource.get_model('pikachu')  # RuntimeError: Failed to download ... ConnectionError\n# after — retry with backoff, fall back to OSS\nimport time\nfor i in range(3):\n    try:\n        path = resource.get_model('pikachu'); break\n    except RuntimeError:\n        time.sleep(2 ** i)\nelse:\n    inspireface.use_oss_download(True)\n    path = resource.get_model('pikachu')","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"import time\nfor attempt in range(3):\n    try:\n        path = resource.get_model(name)\n        break\n    except RuntimeError as e:\n        if attempt == 2:\n            inspireface.use_oss_download(True)\n            path = resource.get_model(name)\n        else:\n            time.sleep(2 ** attempt)","preventionTips":["Vendor/pre-download models into images to avoid runtime downloads","Set HTTPS_PROXY in corporate networks; monitor disk space in cache dirs"],"tags":["download","network","modelscope","retryable"],"backgroundTag":"model-download-failed","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}