{"record":{"id":"00ad01ae86d1d3d3","repo":"deepinsight/insightface","slug":"no-face-detected","errorCode":null,"errorMessage":"no face detected","messagePattern":"no face detected","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"warning","filePath":"python-package/insightface/gui/core/evaluation.py","lineNumber":166,"sourceCode":"        bounding_box_size = (det[:, 2] - det[:, 0]) * (det[:, 3] - det[:, 1])\n        img_center = img_size / 2.0\n        offsets = np.vstack(\n            [\n                (det[:, 0] + det[:, 2]) / 2.0 - img_center[1],\n                (det[:, 1] + det[:, 3]) / 2.0 - img_center[0],\n            ]\n        )\n        offset_dist_squared = np.sum(np.power(offsets, 2.0), axis=0)\n        return faces[int(np.argmax(bounding_box_size - offset_dist_squared * 2.0))]\n    except Exception:\n        return max(faces, key=_face_area)\n\n\ndef _select_face_from_faces(faces, image_shape, path: Path, policy: str, stage: str):\n    del path, stage\n    face_count = len(faces)\n    if face_count == 0:\n        raise ValueError(\"no face detected\")\n    if face_count > 1 and policy == MULTI_FACE_REQUIRE_ONE:\n        raise ValueError(f\"multiple faces detected ({face_count}); expected exactly one face\")\n    if face_count > 1 and policy == MULTI_FACE_SKIP:\n        raise ValueError(f\"skipped multi-face image ({face_count} faces)\")\n    if face_count > 1 and policy == MULTI_FACE_USE_CENTERED_LARGEST:\n        return _largest_centered_face(faces, image_shape)\n    if face_count > 1:\n        return max(faces, key=_face_area)\n    return faces[0]\n\n\ndef select_face_by_policy(faces, image_shape, policy: str = MULTI_FACE_REQUIRE_ONE, path: str | Path = \"\", stage: str = \"\"):\n    return _select_face_from_faces(\n        faces,\n        image_shape,\n        Path(path) if path else Path(\"image\"),\n        _normalize_multi_face_policy(policy),\n        stage,","sourceCodeStart":148,"sourceCodeEnd":184,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/python-package/insightface/gui/core/evaluation.py#L148-L184","documentation":"_select_face_from_faces raises ValueError('no face detected') when the detector's face list is empty — the embedding step cannot proceed without a face, regardless of policy (policies only differentiate multi-face cases). Callers reach it through select_face_by_policy / _embedding_for_image during evaluation.","triggerScenarios":"Evaluating an image where FaceAnalysis.get() returns zero faces: dark/blurry/tiny faces, non-face images, det_thresh too high, or det_size too small for the face scale.","commonSituations":"Datasets containing crowd/background images; det_size=(320,320) missing small faces; det_thresh raised too aggressively; wrong BGR/RGB channel order feeding the detector; grayscale/low-res probe photos.","solutions":["Lower det_thresh / increase det_size when creating FaceAnalysis (e.g. det_size=(640,640)).","Skip or blacklist images that legitimately contain no face before evaluation.","Verify image loading channel order and that images actually contain visible faces.","Catch this ValueError per-image in evaluation loops and count it as a 'no-detection' skip metric."],"exampleFix":"# before\nemb = _embedding_for_image(img_path)  # ValueError: no face detected\n\n# after\nfaces = app.get(img)\nif not faces:\n    stats['no_face'] += 1\n    continue  # skip image\nemb = _embedding_for_image(img_path)","handlingStrategy":"try-catch","validationCode":"faces = app.get(img)\nif not faces:\n    skip(image_path)  # no face — do not call the embedding step","typeGuard":"def has_detectable_face(faces) -> bool:\n    return len(faces) >= 1","tryCatchPattern":"try:\n    emb = _embedding_for_image(p)\nexcept ValueError as e:\n    if str(e) == 'no face detected':\n        stats['no_face'] += 1\n        continue\n    raise","preventionTips":["Pre-filter datasets with the detector before evaluation.","Tune det_size/det_thresh for small or low-quality faces.","Track no-detection counts as a data-quality metric."],"tags":["face-detection","evaluation","empty-result"],"backgroundTag":"face-detection-no-faces","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}