deepinsight/insightface · error · RuntimeError

Failed to download model from ModelScope: {e}

Error message

Failed to download model from ModelScope: {e}

What it means

_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.

Source

Thrown at cpp-package/inspireface/python/inspireface/modules/utils/resource.py:139

        
        try:
            # Download specific model file from ModelScope
            cache_dir = snapshot_download(
                model_id=self.modelscope_model_id,
                cache_dir=str(self.modelscope_cache_dir),
                allow_file_pattern=[model_name]  # Only download the specific model file
            )
            
            model_file_path = Path(cache_dir) / model_name
            
            if not model_file_path.exists():
                raise FileNotFoundError(f"Model file '{model_name}' not found in downloaded repository")
                
            print(f"ModelScope download completed: {model_file_path}")
            return str(model_file_path)
            
        except Exception as e:
            raise RuntimeError(f"Failed to download model from ModelScope: {e}")

    def get_model(self, name: str, re_download: bool = False, ignore_verification: bool = False) -> str:
        """
        Get model path. Download if not exists or re_download is True.
        
        Args:
            name: Model name
            re_download: Force re-download if True
            ignore_verification: Skip model hash verification if True
            
        Returns:
            str: Full path to model file
        """
        # Check global OSS setting first, then instance setting
        use_oss = USE_OSS_DOWNLOAD
        use_modelscope_actual = self.use_modelscope and not use_oss
        
        # Use ModelScope download if enabled and OSS is not forced

View on GitHub (pinned to 7fadd420c2)

Solutions

1. Read the embedded {e} message to identify network vs auth vs disk cause
2. Retry with a stable network / configure HTTPS_PROXY if behind a corporate proxy
3. Pre-download the model (or vendor it into the image) and place it in the models dir so no runtime download occurs
4. If modelscope is flaky, switch to OSS: inspireface.use_oss_download(True)

Example fix

# before
path = resource.get_model('pikachu')  # RuntimeError: Failed to download ... ConnectionError
# after — retry with backoff, fall back to OSS
import time
for i in range(3):
    try:
        path = resource.get_model('pikachu'); break
    except RuntimeError:
        time.sleep(2 ** i)
else:
    inspireface.use_oss_download(True)
    path = resource.get_model('pikachu')

import time
for attempt in range(3):
    try:
        path = resource.get_model(name)
        break
    except RuntimeError as e:
        if attempt == 2:
            inspireface.use_oss_download(True)
            path = resource.get_model(name)
        else:
            time.sleep(2 ** attempt)

When it happens

Trigger: 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.

Common situations: Corporate proxies/firewalls blocking modelscope.cn or CDN; flaky CI networks; expired/invalid modelscope credentials for gated repos; full disk in the cache directory.

Related errors

• ModelScope is not available. You have two options: 1. Instal
• ModelScope is not available. Please install it with: pip ins
• Model file '{model_name}' not found in downloaded repository
• Failed to download model: {e}

AI-assisted analysis of deepinsight/insightface@7fadd420c2 (2026-08-28). Data as JSON: /api/errors/208b503b334e63fc. Report an issue: GitHub.