{"record":{"id":"cccc0a88b380af0d","repo":"deepinsight/insightface","slug":"no-usable-face-detected-in-source-image","errorCode":null,"errorMessage":"No usable face detected in source image.","messagePattern":"No usable face detected in source image\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python-package/insightface/gui/pages/face_swap_page.py","lineNumber":172,"sourceCode":"            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                )\n            else:\n                self.output_image = result.get(\"preview\")\n                self.output_video_path = result[\"path\"]","sourceCodeStart":154,"sourceCodeEnd":190,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/python-package/insightface/gui/pages/face_swap_page.py#L154-L190","documentation":"The source image for the face swap either produced no face detection or the detected face lacks a normed_embedding, so there is no identity to swap from. It is thrown by the GUI task before any swapping occurs.","triggerScenarios":"Calling face swap with a source image containing no detectable face, a heavily occluded/tiny/blurred face, or when detection succeeded but embedding extraction returned None.","commonSituations":"Using cartoon/animated images, faces too small for the det_size, wrong image orientation (EXIF rotation), poor lighting, or a corrupt image that decodes to garbage.","solutions":["Use a clear, front-facing source photo with a single large face","Increase detector det_size (e.g. (640,640)) or try a higher-resolution source image","Verify detection works with the engine's detect API on the source image first","Try a different source photo"],"exampleFix":"# before\nsource_face = engine.detect_best_face(source_image)\n# after\nsource_face = engine.detect_best_face(source_image)\nif source_face is None:\n    dets = engine.get(np.asarray(source_image), max_num=0)\n    if not dets:\n        raise SystemExit(\"No face found - use a clearer source photo\")","handlingStrategy":"validation","validationCode":"face = engine.detect_best_face(source_image, source_path=path)\nif face is None or face.normed_embedding is None:\n    # upscale and retry before giving up\n    source_image = cv2.resize(source_image, None, fx=2, fy=2)","typeGuard":"def has_embedding(face) -> bool:\n    return face is not None and getattr(face, \"normed_embedding\", None) is not None","tryCatchPattern":"try:\n    ...\nexcept ValueError as e:\n    if \"source image\" in str(e):\n        prompt_user_for_better_source_photo()","preventionTips":["Show a source-image face preview/thumbnail in the UI before starting","Use large, frontal, well-lit source photos","Pre-check detection on the source image before launching the background task"],"tags":["insightface","face-detection","no-face","face-swap"],"backgroundTag":"face-detection-no-face-found","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}