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.

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)

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

• image read failure
• Face swap model load failed: {exc}
• No usable face detected in source image.
• No usable face detected in target image.
• skipped multi-face image ({face_count} faces)

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