deepinsight/insightface · error · ValueError

No usable face detected in target image.

Error message

No usable face detected in target image.

What it means

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.

Source

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

        self.run_task("Running face swap", task, done)

    def open_result(self) -> None:
        if self.output_path and Path(self.output_path).exists():
            QDesktopServices.openUrl(QUrl.fromLocalFile(self.output_path))
            return
        self.show_error("No saved result file to open.")

    def open_result_directory(self) -> None:
        folder = Path(self.output_path).parent if self.output_path else Path(self.context.config.export_dir)
        folder.mkdir(parents=True, exist_ok=True)
        QDesktopServices.openUrl(QUrl.fromLocalFile(str(folder)))

    def _swap_image(self, swapper: FaceSwapEngine, source_native, target_image, target_path: str) -> dict:
        if target_image is None:
            raise ValueError("Target image could not be read.")
        target_face = self.context.engine.detect_best_face(target_image, source_path=target_path)
        if target_face is None or target_face.kps is None:
            raise ValueError("No usable face detected in target image.")
        target_native = SimpleNamespace(kps=np.asarray(target_face.kps, dtype=np.float32))
        image = swapper.swap(target_image, target_native, source_native)
        output_path = Path(self.context.config.export_dir) / f"face_swap_{timestamp_for_filename()}.png"
        save_image(output_path, image)
        return {
            "kind": "image",
            "image": image,
            "path": str(output_path),
            "message": f"Image face swap saved to {output_path}",
        }

    def _swap_video(self, swapper: FaceSwapEngine, source_native, target_path: str, progress=None, is_cancelled=None) -> dict:
        try:
            import cv2
        except Exception as exc:
            raise ValueError(f"OpenCV is required for video face swap: {exc}") from exc

        cap = cv2.VideoCapture(target_path)

View on GitHub (pinned to 7fadd420c2)

Solutions

1. Use a target image with a clear, reasonably large face
2. Increase detector input size (det_size) so small faces are found
3. Fix image orientation (apply EXIF rotation) before swapping
4. If the target truly has no face, use a different target image

Example fix

# before
img = cv2.imread(path)
# after
img = cv2.imread(path)
if img is not None:
    img = cv2.exifRotate(path) if hasattr(cv2, 'exifRotate') else img
# and set larger det_size on the detector session
detector.prepare(ctx_id=0, det_size=(640,640))

target_face = engine.detect_best_face(target_image, source_path=target_path)
if target_face is None or target_face.kps is None:
    engine.detector.prepare(ctx_id=0, det_size=(640, 640))
    target_face = engine.detect_best_face(target_image, source_path=target_path)

def has_kps(face) -> bool:
    return face is not None and getattr(face, "kps", None) is not None

try:
    return self._swap_image(...)
except ValueError as e:
    if "target image" in str(e): suggest_higher_resolution_target()

When it happens

Trigger: Target image has no detectable face, or the detected face object has kps=None so alignment landmarks are unavailable.

Common situations: Group/crowd photos with tiny faces, side profiles, dark or blurred targets, wrong image orientation, or target images that are screenshots/low quality.

Related errors

• No usable face detected in source image.
• skipped multi-face image ({face_count} faces)
• no face or embedding
• Face swap model load failed: {exc}
• Target image could not be read.

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