{"record":{"id":"eec638a41df8cda4","repo":"deepinsight/insightface","slug":"image-read-failure","errorCode":null,"errorMessage":"image read failure","messagePattern":"image read failure","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python-package/insightface/gui/core/evaluation.py","lineNumber":208,"sourceCode":"    if policy == MULTI_FACE_REQUIRE_ONE:\n        return \"Multi-face policy: require exactly one face. Images with multiple detected faces fail with a clear error.\"\n    if policy == MULTI_FACE_USE_LARGEST:\n        return \"Multi-face policy: use largest face. If an image has multiple faces, the largest detected face is used.\"\n    if policy == MULTI_FACE_USE_CENTERED_LARGEST:\n        return (\n            \"Multi-face policy: use largest centered face. If an image has multiple faces, the face with the best \"\n            \"area-minus-center-distance score is used.\"\n        )\n    return (\n        \"Multi-face policy: mark as skip. Gallery images with multiple detected faces are skipped; a multi-face query \"\n        \"stops the current run.\"\n    )\n\n\ndef _detect_faces_for_image(path: Path, engine: FaceEngine):\n    img = read_image(path)\n    if img is None:\n        raise ValueError(\"image read failure\")\n    return img, engine.detect_faces(img, source_path=str(path))\n\n\ndef _embedding_for_image(\n    path: Path,\n    engine: FaceEngine,\n    cache: Dict[str, np.ndarray],\n    errors: List[Dict[str, Any]],\n    stage: str,\n    multi_face_policy: str = MULTI_FACE_REQUIRE_ONE,\n) -> Optional[np.ndarray]:\n    key = str(path)\n    if key in cache:\n        return cache[key]\n    policy = _normalize_multi_face_policy(multi_face_policy)\n    try:\n        image, faces = _detect_faces_for_image(path, engine)\n        face = _select_face_from_faces(faces, image.shape, path, policy, stage)","sourceCodeStart":190,"sourceCodeEnd":226,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/python-package/insightface/gui/core/evaluation.py#L190-L226","documentation":"Raised by _detect_faces_for_image when read_image returns None for a path, meaning the file could not be loaded as an image (missing, corrupt, unsupported, or unreadable). Detection never runs; the caller (_embedding_for_image or _validate_image_spec) records the failure or propagates it.","triggerScenarios":"Passing a nonexistent path, a corrupt/truncated file, a non-image file, or an unreadable (permissions/codec) file to an evaluation that calls _detect_faces_for_image.","commonSituations":"Dataset manifests with stale paths; files with wrong extension (.jpg that is actually text); CMYK/exotic JPEG variants; files synced partially; permission issues on mounted storage.","solutions":["Verify the path exists and is a regular file before evaluation (Path.is_file())","Open the file with PIL/cv2 manually to identify corrupt or unsupported images","Re-encode problematic images to standard RGB JPEG/PNG","Filter bad paths up front with a validation pass using list_images/_validate_image_spec"],"exampleFix":"# before\nimage, faces = _detect_faces_for_image(path, engine)\n# after\nif not path.is_file():\n    raise FileNotFoundError(path)\nimage, faces = _detect_faces_for_image(path, engine)","handlingStrategy":"validation","validationCode":"from pathlib import Path\nfrom PIL import Image\np = Path(path)\nassert p.is_file()\nwith Image.open(p) as im:\n    im.verify()  # raises on corrupt files","typeGuard":null,"tryCatchPattern":"try:\n    image, faces = _detect_faces_for_image(path, engine)\nexcept ValueError as e:\n    if \"image read failure\" in str(e):\n        log_bad_image(path); skip(path)","preventionTips":["Validate files at ingestion (magic bytes + PIL verify)","Keep dataset manifests in sync with actual files","Re-encode exotic formats to standard JPEG/PNG"],"tags":["insightface","image-io","corrupt-file","evaluation"],"backgroundTag":"image-read-failed","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}