{"record":{"id":"84790b86997cd847","repo":"deepinsight/insightface","slug":"target-image-could-not-be-read","errorCode":null,"errorMessage":"Target image could not be read.","messagePattern":"Target image could not be read\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python-package/insightface/gui/pages/face_swap_page.py","lineNumber":215,"sourceCode":"                )\n            self.set_status(result[\"message\"])\n\n        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:","sourceCodeStart":197,"sourceCodeEnd":233,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/python-package/insightface/gui/pages/face_swap_page.py#L197-L233","documentation":"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.","triggerScenarios":"Running the image face swap task when the target file failed to load (unreadable, unsupported format, or path pointing at nothing).","commonSituations":"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.","solutions":["Open the target image in an image viewer to confirm it is valid","Re-encode the image to PNG/JPEG and retry","Check the file path is correct and readable (permissions, mounted drive)","Validate the image decodes before starting the swap task"],"exampleFix":"# before\nimg = load_image(path)\nresult = self._swap_image(swapper, src, img, path)\n# after\nimg = load_image(path)\nif img is None:\n    raise ValueError(f\"Cannot decode {path} - convert to PNG and retry\")\nresult = self._swap_image(swapper, src, img, path)","handlingStrategy":"validation","validationCode":"img = load_image(target_path)\nif img is None or not hasattr(img, 'shape') or img.ndim < 2:\n    raise ValueError('target unreadable - ask user to re-select file')","typeGuard":"def is_readable_image(img) -> bool:\n    return img is not None and getattr(img, \"size\", 0) > 0","tryCatchPattern":"try:\n    return self._swap_image(swapper, src, img, path)\nexcept ValueError as e:\n    if \"could not be read\" in str(e): reselect_file_dialog()","preventionTips":["Validate decodability at file-selection time in the UI","Convert exotic formats (HEIC/TIFF) to PNG up front","Surface decode errors before the expensive model loads"],"tags":["insightface","image-io","decode","face-swap"],"backgroundTag":"image-decode-failed","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}