deepinsight/insightface · error · ValueError

Target image could not be read.

Error message

Target image could not be read.

What it means

The target image passed into _swap_image is None, meaning the image selected/dropped by the user could not be decoded into an array before the swap was attempted.

Solutions

1. Open the target image in an image viewer to confirm it is valid
2. Re-encode the image to PNG/JPEG and retry
3. Check the file path is correct and readable (permissions, mounted drive)
4. Validate the image decodes before starting the swap task

Example fix

# before
img = load_image(path)
result = self._swap_image(swapper, src, img, path)
# after
img = load_image(path)
if img is None:
    raise ValueError(f"Cannot decode {path} - convert to PNG and retry")
result = self._swap_image(swapper, src, img, path)

img = load_image(target_path)
if img is None or not hasattr(img, 'shape') or img.ndim < 2:
    raise ValueError('target unreadable - ask user to re-select file')

def is_readable_image(img) -> bool:
    return img is not None and getattr(img, "size", 0) > 0

try:
    return self._swap_image(swapper, src, img, path)
except ValueError as e:
    if "could not be read" in str(e): reselect_file_dialog()

When it happens

Trigger: Running the image face swap task when the target file failed to load (unreadable, unsupported format, or path pointing at nothing).

Common situations: Corrupt or truncated image files, non-image files with an image extension, unsupported formats (e.g. HEIC without Pillow plugin), or the file being moved/deleted after selection.

Related errors

• Face swap model load failed
• image read failure
• No usable face detected in source image.
• No usable face detected in target image.
• 1:N evaluation requires at least one gallery image.

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

Appendix: source

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

                )
            self.set_status(result["message"])

        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:

View on GitHub (pinned to 7fadd420c2)