deepinsight/insightface · error · ValueError

Face swap model load failed: {exc}

Error message

Face swap model load failed: {exc}

What it means

Raised when the face swap model fails to load: either swapper.load() returned False (with the reason in swapper.last_error) or model construction raised an exception (captured into the formatted message). This is an InsightFace GUI face-swap pipeline error indicating the ONNX inswapper/gfpgan models could not be initialized.

Source

Thrown at python-package/insightface/gui/pages/face_swap_page.py:169

        model_path = self._resolve_swap_model_path()
        if not model_path:
            self.show_error("Face swap model not found. Please download and choose a swap model in Models.")
            return

        source_image = self.source_image.copy()
        target_path = self.target_path
        target_kind = self.target_kind
        target_image = self.target_image.copy() if self.target_image is not None and target_kind == "image" else None

        def task(progress=None, is_cancelled=None):
            swapper = FaceSwapEngine(
                model_path,
                providers_from_choice(self.context.config.provider),
                gfpgan_model_path=getattr(self.context.config, "gfpgan_model_path", ""),
                enable_gfpgan=bool(getattr(self.context.config, "enable_gfpgan", False)),
            )
            if not swapper.load():
                raise ValueError(swapper.last_error)
            source_face = self.context.engine.detect_best_face(source_image, source_path=self.source_path)
            if source_face is None or source_face.normed_embedding is None:
                raise ValueError("No usable face detected in source image.")
            source_native = SimpleNamespace(normed_embedding=source_face.normed_embedding)
            if target_kind == "image":
                return self._swap_image(swapper, source_native, target_image, target_path)
            return self._swap_video(swapper, source_native, target_path, progress, is_cancelled)

        def done(result):
            if result["kind"] == "image":
                self.output_image = result["image"]
                self.output_video_path = ""
                self.output_path = result["path"]
                self.output_view.set_image(self.output_image)
                self.result_label.setText(
                    tr("Image swap saved. Click Result to open it.", self.context.config.ui_language)
                    + f"\n{self.output_path}"
                )

View on GitHub (pinned to 7fadd420c2)

Solutions

1. Check swapper.last_error / the formatted exception text for the underlying cause
2. Verify the inswapper model path exists and is a valid ONNX file; re-download if corrupt
3. Confirm the selected provider is installed (pip install onnxruntime-gpu for CUDA) and GPU drivers work
4. Disable GFPGAN or point gfpgan_model_path at a valid GFPGAN v1.4 .onnx file

Example fix

# before
swapper = FaceSwapEngine(model_path, providers_from_choice("cuda"))
# after
import onnxruntime as ort
avail = ort.get_available_providers()
swapper = FaceSwapEngine(model_path, providers_from_choice("cuda" if "CUDAExecutionProvider" in avail else "cpu"))

import os
from onnxruntime import get_available_providers
prov = providers_from_choice(cfg.provider) if "CUDAExecutionProvider" not in get_available_providers() else providers_from_choice("cpu")
assert os.path.isfile(model_path) and model_path.endswith(".onnx")

try:
    if not swapper.load():
        raise ValueError(swapper.last_error)
except ValueError as e:
    log.error("swap model unavailable: %s", e); show_dialog(str(e))

When it happens

Trigger: Calling the face swap task when the inswapper_128.onnx model file is missing, the ONNX Runtime execution provider (e.g. CUDAExecutionProvider) is unavailable, or the GFPGAN model path is configured but invalid.

Common situations: Fresh install without downloaded model weights, wrong model_root path, requesting the CUDA provider on a CPU-only ONNX Runtime build, or a corrupt/incompatible ONNX file after a version change.

Related errors

• No usable face detected in source image.
• Target image could not be read.
• No usable face detected in target image.
• skipped multi-face image ({face_count} faces)
• image read failure

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