deepinsight/insightface · warning · ValueError

skipped multi-face image ({face_count} faces)

Error message

skipped multi-face image ({face_count} faces)

What it means

Raised by _select_face_from_faces when an image contains more than one face and the multi-face policy is MULTI_FACE_SKIP. The evaluation refuses to guess which face is the subject, so the image is treated as unusable for that stage. It is one of several policy-driven ValueError branches handling multi-face ambiguity.

Source

Thrown at python-package/insightface/gui/core/evaluation.py:170

                (det[:, 0] + det[:, 2]) / 2.0 - img_center[1],
                (det[:, 1] + det[:, 3]) / 2.0 - img_center[0],
            ]
        )
        offset_dist_squared = np.sum(np.power(offsets, 2.0), axis=0)
        return faces[int(np.argmax(bounding_box_size - offset_dist_squared * 2.0))]
    except Exception:
        return max(faces, key=_face_area)


def _select_face_from_faces(faces, image_shape, path: Path, policy: str, stage: str):
    del path, stage
    face_count = len(faces)
    if face_count == 0:
        raise ValueError("no face detected")
    if face_count > 1 and policy == MULTI_FACE_REQUIRE_ONE:
        raise ValueError(f"multiple faces detected ({face_count}); expected exactly one face")
    if face_count > 1 and policy == MULTI_FACE_SKIP:
        raise ValueError(f"skipped multi-face image ({face_count} faces)")
    if face_count > 1 and policy == MULTI_FACE_USE_CENTERED_LARGEST:
        return _largest_centered_face(faces, image_shape)
    if face_count > 1:
        return max(faces, key=_face_area)
    return faces[0]


def select_face_by_policy(faces, image_shape, policy: str = MULTI_FACE_REQUIRE_ONE, path: str | Path = "", stage: str = ""):
    return _select_face_from_faces(
        faces,
        image_shape,
        Path(path) if path else Path("image"),
        _normalize_multi_face_policy(policy),
        stage,
    )


def multi_face_policy_help(policy: str) -> str:

View on GitHub (pinned to 7fadd420c2)

Solutions

1. Switch multi_face_policy to 'use_largest' or 'centered_largest' so a deterministic face is chosen
2. Curate the dataset to single-face images (crop or remove multi-face files)
3. Pre-scan images with engine.detect_faces and exclude any with len(faces) > 1 before running evaluation
4. If multi-face images are expected to fail, catch the error per-path (errors list already records stage/path) and continue

Example fix

# before
result = run_identity_verification_evaluation(..., multi_face_policy="skip")
# after
result = run_identity_verification_evaluation(..., multi_face_policy="centered_largest")

img = read_image(path)
faces = engine.detect_faces(img, source_path=str(path))
usable = len(faces) == 1 or multi_face_policy != "skip"

try:
    emb = _embedding_for_image(path, engine, multi_face_policy=policy)
except ValueError as e:
    if "skipped multi-face" in str(e):
        continue  # or retry with centered_largest policy

When it happens

Trigger: Calling run_identity_verification_evaluation / run_identity_identification_evaluation (or _embedding_for_image) with multi_face_policy='skip' (or a value normalized to it) on a dataset where images contain 2+ detected faces.

Common situations: Group photos or crowd shots in an identity folder; background posters/faces detected alongside the subject; test fixtures built with collages; policy configured globally as 'skip' but dataset not curated.

Related errors

• multiple faces detected ({face_count}); expected exactly one
• no face or embedding
• no face detected
• image read failure
• No verification pairs could be generated from the selected i

AI-assisted analysis of deepinsight/insightface@7fadd420c2 (2026-08-28). Data as JSON: /api/errors/07aa8c583c3fa3e6. Report an issue: GitHub.