{"record":{"id":"f29799948de30045","repo":"deepinsight/insightface","slug":"no-usable-face-detected-in-target-image","errorCode":null,"errorMessage":"No usable face detected in target image.","messagePattern":"No usable face detected in target image\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python-package/insightface/gui/pages/face_swap_page.py","lineNumber":218,"sourceCode":"        self.run_task(\"Running face swap\", task, done)\n\n    def open_result(self) -> None:\n        if self.output_path and Path(self.output_path).exists():\n            QDesktopServices.openUrl(QUrl.fromLocalFile(self.output_path))\n            return\n        self.show_error(\"No saved result file to open.\")\n\n    def open_result_directory(self) -> None:\n        folder = Path(self.output_path).parent if self.output_path else Path(self.context.config.export_dir)\n        folder.mkdir(parents=True, exist_ok=True)\n        QDesktopServices.openUrl(QUrl.fromLocalFile(str(folder)))\n\n    def _swap_image(self, swapper: FaceSwapEngine, source_native, target_image, target_path: str) -> dict:\n        if target_image is None:\n            raise ValueError(\"Target image could not be read.\")\n        target_face = self.context.engine.detect_best_face(target_image, source_path=target_path)\n        if target_face is None or target_face.kps is None:\n            raise ValueError(\"No usable face detected in target image.\")\n        target_native = SimpleNamespace(kps=np.asarray(target_face.kps, dtype=np.float32))\n        image = swapper.swap(target_image, target_native, source_native)\n        output_path = Path(self.context.config.export_dir) / f\"face_swap_{timestamp_for_filename()}.png\"\n        save_image(output_path, image)\n        return {\n            \"kind\": \"image\",\n            \"image\": image,\n            \"path\": str(output_path),\n            \"message\": f\"Image face swap saved to {output_path}\",\n        }\n\n    def _swap_video(self, swapper: FaceSwapEngine, source_native, target_path: str, progress=None, is_cancelled=None) -> dict:\n        try:\n            import cv2\n        except Exception as exc:\n            raise ValueError(f\"OpenCV is required for video face swap: {exc}\") from exc\n\n        cap = cv2.VideoCapture(target_path)","sourceCodeStart":200,"sourceCodeEnd":236,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/python-package/insightface/gui/pages/face_swap_page.py#L200-L236","documentation":"No face with valid keypoints (kps) was detected in the target image, so the swapper has no region to paste the source face onto. Raised inside _swap_image after target detection.","triggerScenarios":"Target image has no detectable face, or the detected face object has kps=None so alignment landmarks are unavailable.","commonSituations":"Group/crowd photos with tiny faces, side profiles, dark or blurred targets, wrong image orientation, or target images that are screenshots/low quality.","solutions":["Use a target image with a clear, reasonably large face","Increase detector input size (det_size) so small faces are found","Fix image orientation (apply EXIF rotation) before swapping","If the target truly has no face, use a different target image"],"exampleFix":"# before\nimg = cv2.imread(path)\n# after\nimg = cv2.imread(path)\nif img is not None:\n    img = cv2.exifRotate(path) if hasattr(cv2, 'exifRotate') else img\n# and set larger det_size on the detector session\ndetector.prepare(ctx_id=0, det_size=(640,640))","handlingStrategy":"validation","validationCode":"target_face = engine.detect_best_face(target_image, source_path=target_path)\nif target_face is None or target_face.kps is None:\n    engine.detector.prepare(ctx_id=0, det_size=(640, 640))\n    target_face = engine.detect_best_face(target_image, source_path=target_path)","typeGuard":"def has_kps(face) -> bool:\n    return face is not None and getattr(face, \"kps\", None) is not None","tryCatchPattern":"try:\n    return self._swap_image(...)\nexcept ValueError as e:\n    if \"target image\" in str(e): suggest_higher_resolution_target()","preventionTips":["Preview target detection in the UI before swap","Use targets with a clearly visible face","Retry with larger det_size or upscaled target on failure"],"tags":["insightface","face-detection","keypoints","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"}