{"record":{"id":"4ac1bd91147e8c9a","repo":"deepinsight/insightface","slug":"failed-to-download-model-e","errorCode":null,"errorMessage":"Failed to download model: {e}","messagePattern":"Failed to download model: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"cpp-package/inspireface/python/inspireface/modules/utils/resource.py","lineNumber":221,"sourceCode":"                            break\n                        downloaded_size += len(buffer)\n                        f.write(buffer)\n                        \n                        if total_size > 0:\n                            percent = (downloaded_size / total_size) * 100\n                            sys.stdout.write(f\"\\rDownloading {name}: {percent:.1f}%\")\n                            sys.stdout.flush()\n            \n            print(\"\\nDownload completed\")\n            downloading_flag.unlink()  # Remove the downloading flag\n            return str(model_file)\n\n        except Exception as e:\n            if model_file.exists():\n                model_file.unlink()\n            if downloading_flag.exists():\n                downloading_flag.unlink()\n            raise RuntimeError(f\"Failed to download model: {e}\")\n\n    def _download_from_modelscope_with_cache(self, name: str, re_download: bool = False) -> str:\n        \"\"\"Download model from ModelScope with local caching logic\n        \n        Args:\n            name: Model name\n            re_download: Force re-download if True\n            \n        Returns:\n            str: Path to the model file\n        \"\"\"\n        # Check if model exists in ModelScope cache\n        model_file_path = self.modelscope_cache_dir / name\n        \n        if model_file_path.exists() and not re_download:\n            print(f\"Using cached model '{name}' from ModelScope\")\n            return str(model_file_path)\n            ","sourceCodeStart":203,"sourceCodeEnd":239,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/cpp-package/inspireface/python/inspireface/modules/utils/resource.py#L203-L239","documentation":"Raised by inspireface's resource manager when any exception escapes the model-download block (HF/ModelScope fetch). The handler deletes the partially downloaded model file and the 'downloading' flag file, then wraps the original exception in a RuntimeError. It means the model artifact could not be fetched or written into the local cache.","triggerScenarios":"Calling the model download/get_model path in inspireface.modules.utils.resource when the network request or file write inside the try block raises: no internet, HTTP 404 for the model name, proxy/DNS failure, or unwritable cache directory causing the flag/model file operations themselves to fail.","commonSituations":"Offline or firewalled environments (HF blocked), mistyped model names, expired download URLs, read-only HOME so the .cache path can't be created, or a stale downloading_flag left from a previous crashed run.","solutions":["Read the wrapped '{e}' part — it names the root cause (DNS, 404, SSL, permission); fix that first.","Verify network access to the download host and set HTTPS_PROXY if behind a corporate proxy.","Pass the correct model name / use a pre-downloaded local model path instead of triggering the download.","Ensure the cache directory is writable and has disk space; remove stale .download_flag files left by earlier failures."],"exampleFix":"# before\npath = get_model('payer_reid')  # RuntimeError: Failed to download model: HTTPSConnectionPool(host='huggingface.co'...)\n\n# after\nimport os\nos.environ['HTTPS_PROXY'] = 'http://proxy:8080'\ntry:\n    path = get_model('payer_reid')\nexcept RuntimeError as e:\n    print('download failed:', e)\n    path = '/models/payer_reid'  # local fallback","handlingStrategy":"try-catch","validationCode":"import socket, os\nfrom pathlib import Path\n# ensure writable cache location\nassert os.access(Path.home(), os.W_OK)\n# optionally pre-check reachability of the model host\nsocket.create_connection(('huggingface.co', 443), timeout=5)","typeGuard":null,"tryCatchPattern":"try:\n    path = get_model(name)\nexcept RuntimeError as e:\n    if 'Failed to download model' in str(e):\n        path = local_fallback(name)  # use pre-downloaded copy\n    else:\n        raise","preventionTips":["Ship a local model directory for offline deployments.","Set HTTPS_PROXY before first download in corporate networks.","Monitor cache-dir disk space and clean stale .download_flag files."],"tags":["network","download","model-cache","runtimeerror","inspireface"],"backgroundTag":"model-download-failed","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}