deepinsight/insightface · error · ValueError

Model '{name}' not found. Available models: {list(self._MODE

Error message

Model '{name}' not found. Available models: {list(self._MODEL_LIST.keys())}

What it means

In the legacy (non-ModelScope) download path, get_model looks up name in the static _MODEL_LIST registry; an unknown key raises ValueError listing all valid model names. This is pure input validation before any file or network access happens.

Source

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

        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
        if use_modelscope_actual:
            return self._download_from_modelscope_with_cache(name, re_download)
            
        # Original download logic for backwards compatibility
        if name not in self._MODEL_LIST:
            raise ValueError(f"Model '{name}' not found. Available models: {list(self._MODEL_LIST.keys())}")

        model_info = self._MODEL_LIST[name]
        model_file = self.models_dir / model_info["filename"]
        downloading_flag = model_file.with_suffix('.downloading')
        
        # Check if model exists and is complete
        if model_file.exists() and not downloading_flag.exists() and not re_download:
            if ignore_verification:
                print(f"Warning: Model verification skipped for '{name}' as requested.")
                return str(model_file)
                
            current_hash = get_file_hash_sha256(model_file)
            if current_hash == model_info["md5"]:
                return str(model_file)
            else:
                print(f"Model file hash mismatch for '{name}'. Re-downloading...")

        # Start download

View on GitHub (pinned to 7fadd420c2)

Solutions

Use one of the names printed in the error message itself (list(self._MODEL_LIST.keys()))
Print the registry to discover valid names: inspect resource._MODEL_LIST at runtime
If you need a newer/renamed model, upgrade the inspireface package

Example fix

# before
path = resource.get_model('Pikachu')
# after
valid = list(resource._MODEL_LIST)
print(valid)  # see exact keys
path = resource.get_model(valid[0])

Defensive patterns

Strategy: validation

Validate before calling

valid = list(resource._MODEL_LIST.keys())
assert name in valid, f'{name!r} not in {valid}'

Type guard

def is_known_model(resource, name: str) -> bool:
    return name in resource._MODEL_LIST

Try / catch

try:
    path = resource.get_model(name)
except ValueError:
    name = sorted(resource._MODEL_LIST)[0]  # pick a valid model
    path = resource.get_model(name)

Prevention

Derive model names from the registry at runtime instead of hardcoding strings
Re-check valid names after upgrading inspireface

When it happens

Trigger: Calling resource.get_model(name) in OSS mode with a string that isn't a key of _MODEL_LIST (typo, wrong casing, or a model removed/renamed in this version).

Common situations: Upgrading inspireface and re-running old scripts whose model names changed; guessing names like 'Pikachu' vs 'pikachu'; copy-pasting names from outdated docs.

Related errors

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