{"record":{"id":"91dd577578827c50","repo":"deepinsight/insightface","slug":"failed-detection","errorCode":null,"errorMessage":"failed detection","messagePattern":"failed detection","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"warning","filePath":"python-package/insightface/gui/core/evaluation.py","lineNumber":1008,"sourceCode":"        pairs = list(reader)\n    start_all = time.perf_counter()\n    for index, row in enumerate(pairs):\n        if cancel_callback and cancel_callback():\n            break\n        image1_path = row.get(\"image1_path\") or row.get(\"image1\") or \"\"\n        image2_path = row.get(\"image2_path\") or row.get(\"image2\") or \"\"\n        label = int(row.get(\"label\", \"0\"))\n        item: Dict[str, Any] = {\"image1_path\": image1_path, \"image2_path\": image2_path, \"label\": label}\n        start = time.perf_counter()\n        try:\n            img1 = read_image(image1_path)\n            img2 = read_image(image2_path)\n            if img1 is None or img2 is None:\n                raise ValueError(\"image read failure\")\n            face1 = engine.detect_best_face(img1, source_path=image1_path)\n            face2 = engine.detect_best_face(img2, source_path=image2_path)\n            if face1 is None or face2 is None:\n                raise ValueError(\"failed detection\")\n            if face1.normed_embedding is None or face2.normed_embedding is None:\n                raise ValueError(\"embedding unavailable\")\n            similarity = cosine_similarity(face1.normed_embedding, face2.normed_embedding)\n            item.update(\n                {\n                    \"similarity\": similarity,\n                    \"predicted\": 1 if similarity >= threshold else 0,\n                    \"latency_ms\": (time.perf_counter() - start) * 1000.0,\n                }\n            )\n        except Exception as exc:\n            item.update({\"similarity\": None, \"predicted\": None, \"error\": str(exc)})\n            errors.append({\"index\": index, \"error\": str(exc), \"row\": dict(row)})\n        rows.append(item)\n        if progress_callback:\n            progress_callback(index + 1, len(pairs), f\"Processed pair {index + 1}/{len(pairs)}\")\n\n    completed = [row for row in rows if row.get(\"similarity\") is not None]","sourceCodeStart":990,"sourceCodeEnd":1026,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/python-package/insightface/gui/core/evaluation.py#L990-L1026","documentation":"Raised by run_kyc_pairs_evaluation when engine.detect_best_face returns None for one or both images of a KYC pair, meaning the face detector found no usable face. It is a data-quality failure for that pair, not a library bug.","triggerScenarios":"Calling run_kyc_pairs_evaluation with a pair where either image has no detectable face (too small, occluded, rotated, wrong orientation) or detection was skipped because the image is empty after decoding.","commonSituations":"Document scans (ID cards, passports) with tiny face regions, EXIF-rotated photos, low-resolution selfies, or blank/corrupt files dropped into the evaluation dataset.","solutions":["Verify both images actually contain a visible, reasonably sized face (manually inspect the pair reported in the failing item)","Pre-orient images (apply EXIF rotation / deskew scans) before running the evaluation","If images are ID scans, crop or upscale the face region so the detector's minimum size is met","Treat the item as skipped/errored in the report rather than aborting the whole run"],"exampleFix":"// before\nface1 = engine.detect_best_face(img1, source_path=image1_path)\nface2 = engine.detect_best_face(img2, source_path=image2_path)\nif face1 is None or face2 is None:\n    raise ValueError(\"failed detection\")\n// after\nface1 = engine.detect_best_face(img1, source_path=image1_path)\nface2 = engine.detect_best_face(img2, source_path=image2_path)\nif face1 is None or face2 is None:\n    item.update({\"similarity\": None, \"predicted\": None, \"error\": \"failed detection\"})\n    continue","handlingStrategy":"validation","validationCode":"face1 = engine.detect_best_face(img1)\nface2 = engine.detect_best_face(img2)\nif face1 is None or face2 is None:\n    skip_pair(\"no face in pair\")","typeGuard":"def pair_is_scorable(img1, img2) -> bool:\n    f1 = engine.detect_best_face(img1)\n    f2 = engine.detect_best_face(img2)\n    return f1 is not None and f2 is not None","tryCatchPattern":"try:\n    run_kyc_pairs_evaluation(...)\nexcept ValueError as e:\n    if str(e) == \"failed detection\": mark_pair_errored()","preventionTips":["Curate evaluation pairs so each image contains one clear face","Auto-orient images before evaluation","Report per-pair errors instead of failing the run"],"tags":["face-detection","kyc","evaluation","data-quality"],"backgroundTag":"face-detection-no-face-found","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}