{"record":{"id":"e14e54a5ce907391","repo":"deepinsight/insightface","slug":"face-swap-model-load-failed-exc","errorCode":null,"errorMessage":"Face swap model load failed: {exc}","messagePattern":"Face swap model load failed: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python-package/insightface/gui/pages/face_swap_page.py","lineNumber":169,"sourceCode":"        model_path = self._resolve_swap_model_path()\n        if not model_path:\n            self.show_error(\"Face swap model not found. Please download and choose a swap model in Models.\")\n            return\n\n        source_image = self.source_image.copy()\n        target_path = self.target_path\n        target_kind = self.target_kind\n        target_image = self.target_image.copy() if self.target_image is not None and target_kind == \"image\" else None\n\n        def task(progress=None, is_cancelled=None):\n            swapper = FaceSwapEngine(\n                model_path,\n                providers_from_choice(self.context.config.provider),\n                gfpgan_model_path=getattr(self.context.config, \"gfpgan_model_path\", \"\"),\n                enable_gfpgan=bool(getattr(self.context.config, \"enable_gfpgan\", False)),\n            )\n            if not swapper.load():\n                raise ValueError(swapper.last_error)\n            source_face = self.context.engine.detect_best_face(source_image, source_path=self.source_path)\n            if source_face is None or source_face.normed_embedding is None:\n                raise ValueError(\"No usable face detected in source image.\")\n            source_native = SimpleNamespace(normed_embedding=source_face.normed_embedding)\n            if target_kind == \"image\":\n                return self._swap_image(swapper, source_native, target_image, target_path)\n            return self._swap_video(swapper, source_native, target_path, progress, is_cancelled)\n\n        def done(result):\n            if result[\"kind\"] == \"image\":\n                self.output_image = result[\"image\"]\n                self.output_video_path = \"\"\n                self.output_path = result[\"path\"]\n                self.output_view.set_image(self.output_image)\n                self.result_label.setText(\n                    tr(\"Image swap saved. Click Result to open it.\", self.context.config.ui_language)\n                    + f\"\\n{self.output_path}\"\n                )","sourceCodeStart":151,"sourceCodeEnd":187,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/python-package/insightface/gui/pages/face_swap_page.py#L151-L187","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check swapper.last_error / the formatted exception text for the underlying cause","Verify the inswapper model path exists and is a valid ONNX file; re-download if corrupt","Confirm the selected provider is installed (pip install onnxruntime-gpu for CUDA) and GPU drivers work","Disable GFPGAN or point gfpgan_model_path at a valid GFPGAN v1.4 .onnx file"],"exampleFix":"# before\nswapper = FaceSwapEngine(model_path, providers_from_choice(\"cuda\"))\n# after\nimport onnxruntime as ort\navail = ort.get_available_providers()\nswapper = FaceSwapEngine(model_path, providers_from_choice(\"cuda\" if \"CUDAExecutionProvider\" in avail else \"cpu\"))","handlingStrategy":"try-catch","validationCode":"import os\nfrom onnxruntime import get_available_providers\nprov = providers_from_choice(cfg.provider) if \"CUDAExecutionProvider\" not in get_available_providers() else providers_from_choice(\"cpu\")\nassert os.path.isfile(model_path) and model_path.endswith(\".onnx\")","typeGuard":null,"tryCatchPattern":"try:\n    if not swapper.load():\n        raise ValueError(swapper.last_error)\nexcept ValueError as e:\n    log.error(\"swap model unavailable: %s\", e); show_dialog(str(e))","preventionTips":["Pre-download and pin model weights; checksum them at startup","Validate provider availability before constructing the engine","Fail fast on missing model paths in config validation"],"tags":["insightface","face-swap","model-load","onnx"],"backgroundTag":"model-load-failed","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}