deepinsight/insightface · error · RuntimeError

Failed to download model: {e}

Error message

Failed to download model: {e}

What it means

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.

Source

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

                            break
                        downloaded_size += len(buffer)
                        f.write(buffer)
                        
                        if total_size > 0:
                            percent = (downloaded_size / total_size) * 100
                            sys.stdout.write(f"\rDownloading {name}: {percent:.1f}%")
                            sys.stdout.flush()
            
            print("\nDownload completed")
            downloading_flag.unlink()  # Remove the downloading flag
            return str(model_file)

        except Exception as e:
            if model_file.exists():
                model_file.unlink()
            if downloading_flag.exists():
                downloading_flag.unlink()
            raise RuntimeError(f"Failed to download model: {e}")

    def _download_from_modelscope_with_cache(self, name: str, re_download: bool = False) -> str:
        """Download model from ModelScope with local caching logic
        
        Args:
            name: Model name
            re_download: Force re-download if True
            
        Returns:
            str: Path to the model file
        """
        # Check if model exists in ModelScope cache
        model_file_path = self.modelscope_cache_dir / name
        
        if model_file_path.exists() and not re_download:
            print(f"Using cached model '{name}' from ModelScope")
            return str(model_file_path)

View on GitHub (pinned to 7fadd420c2)

Solutions

  1. Read the wrapped '{e}' part — it names the root cause (DNS, 404, SSL, permission); fix that first.
  2. Verify network access to the download host and set HTTPS_PROXY if behind a corporate proxy.
  3. Pass the correct model name / use a pre-downloaded local model path instead of triggering the download.
  4. Ensure the cache directory is writable and has disk space; remove stale .download_flag files left by earlier failures.

Example fix

# before
path = get_model('payer_reid')  # RuntimeError: Failed to download model: HTTPSConnectionPool(host='huggingface.co'...)

# after
import os
os.environ['HTTPS_PROXY'] = 'http://proxy:8080'
try:
    path = get_model('payer_reid')
except RuntimeError as e:
    print('download failed:', e)
    path = '/models/payer_reid'  # local fallback
Defensive patterns

Strategy: try-catch

Validate before calling

import socket, os
from pathlib import Path
# ensure writable cache location
assert os.access(Path.home(), os.W_OK)
# optionally pre-check reachability of the model host
socket.create_connection(('huggingface.co', 443), timeout=5)

Try / catch

try:
    path = get_model(name)
except RuntimeError as e:
    if 'Failed to download model' in str(e):
        path = local_fallback(name)  # use pre-downloaded copy
    else:
        raise

Prevention

When it happens

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

Common situations: 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.

Related errors

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