deepinsight/insightface · error · ValueError

No usable face detected in source image.

Error message

No usable face detected in source image.

What it means

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.

Source

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

            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}"
                )
            else:
                self.output_image = result.get("preview")
                self.output_video_path = result["path"]

View on GitHub (pinned to 7fadd420c2)

Solutions

1. Use a clear, front-facing source photo with a single large face
2. Increase detector det_size (e.g. (640,640)) or try a higher-resolution source image
3. Verify detection works with the engine's detect API on the source image first
4. Try a different source photo

Example fix

# before
source_face = engine.detect_best_face(source_image)
# after
source_face = engine.detect_best_face(source_image)
if source_face is None:
    dets = engine.get(np.asarray(source_image), max_num=0)
    if not dets:
        raise SystemExit("No face found - use a clearer source photo")

face = engine.detect_best_face(source_image, source_path=path)
if face is None or face.normed_embedding is None:
    # upscale and retry before giving up
    source_image = cv2.resize(source_image, None, fx=2, fy=2)

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

try:
    ...
except ValueError as e:
    if "source image" in str(e):
        prompt_user_for_better_source_photo()

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• No usable face detected in target 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/cccc0a88b380af0d. Report an issue: GitHub.