{"record":{"id":"576f6b2f6290ffef","repo":"deepinsight/insightface","slug":"multiple-faces-detected-face-count-expected-e","errorCode":null,"errorMessage":"multiple faces detected ({face_count}); expected exactly one face","messagePattern":"multiple faces detected \\((.+?)\\); expected exactly one face","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"warning","filePath":"python-package/insightface/gui/core/evaluation.py","lineNumber":168,"sourceCode":"        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,\n    )\n","sourceCodeStart":150,"sourceCodeEnd":186,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/python-package/insightface/gui/core/evaluation.py#L150-L186","documentation":"Under the MULTI_FACE_REQUIRE_ONE policy, _select_face_from_faces raises ValueError('multiple faces detected (N); expected exactly one face') whenever the detector returns more than one face. The strict policy refuses to pick among candidates, so strict 1:1 evaluation aborts on any multi-identity image (or spurious extra detection).","triggerScenarios":"Calling select_face_by_policy / _embedding_for_image with policy=MULTI_FACE_REQUIRE_ONE on an image where len(faces) > 1 — group photos, posters, background bystanders, or false-positive boxes.","commonSituations":"Strict verification datasets polluted with group photos; det_thresh too low producing spurious boxes (hands, hair, wall patterns); casual selfie datasets with photobombers.","solutions":["Switch policy to MULTI_FACE_USE_CENTERED_LARGEST (deterministic largest centered face) or MULTI_FACE_SKIP for such datasets.","Raise det_thresh to suppress low-confidence spurious detections.","Curate the dataset: remove or crop multi-identity images before strict evaluation.","Catch this ValueError per-image when require_one is mandated and report skips instead of aborting the run."],"exampleFix":"# before\nface = select_face_by_policy(faces, img.shape, policy=MULTI_FACE_REQUIRE_ONE)  # ValueError: multiple faces detected (3)\n\n# after\ntry:\n    face = select_face_by_policy(faces, img.shape, policy=MULTI_FACE_REQUIRE_ONE)\nexcept ValueError as e:\n    if 'multiple faces detected' in str(e):\n        face = select_face_by_policy(faces, img.shape, policy=MULTI_FACE_USE_CENTERED_LARGEST)\n    else:\n        raise","handlingStrategy":"fallback","validationCode":"faces = app.get(img)\nif len(faces) > 1 and policy == MULTI_FACE_REQUIRE_ONE:\n    policy = MULTI_FACE_USE_CENTERED_LARGEST  # or skip this image","typeGuard":"def is_single_face_image(faces) -> bool:\n    return len(faces) == 1","tryCatchPattern":"try:\n    face = select_face_by_policy(faces, shape, policy=MULTI_FACE_REQUIRE_ONE)\nexcept ValueError as e:\n    if 'multiple faces detected' in str(e):\n        face = select_face_by_policy(faces, shape, policy=MULTI_FACE_USE_CENTERED_LARGEST)\n    else:\n        raise","preventionTips":["Choose permissive policies for in-the-wild datasets.","Raise det_thresh to cut spurious detections.","Pre-crop multi-identity images for strict 1:1 benchmarks."],"tags":["face-detection","multi-face","policy","evaluation"],"backgroundTag":"multiple-faces-detected","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}