deepinsight/insightface · warning · ValueError

failed detection

Error message

failed detection

What it means

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.

Source

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

        pairs = list(reader)
    start_all = time.perf_counter()
    for index, row in enumerate(pairs):
        if cancel_callback and cancel_callback():
            break
        image1_path = row.get("image1_path") or row.get("image1") or ""
        image2_path = row.get("image2_path") or row.get("image2") or ""
        label = int(row.get("label", "0"))
        item: Dict[str, Any] = {"image1_path": image1_path, "image2_path": image2_path, "label": label}
        start = time.perf_counter()
        try:
            img1 = read_image(image1_path)
            img2 = read_image(image2_path)
            if img1 is None or img2 is None:
                raise ValueError("image read failure")
            face1 = engine.detect_best_face(img1, source_path=image1_path)
            face2 = engine.detect_best_face(img2, source_path=image2_path)
            if face1 is None or face2 is None:
                raise ValueError("failed detection")
            if face1.normed_embedding is None or face2.normed_embedding is None:
                raise ValueError("embedding unavailable")
            similarity = cosine_similarity(face1.normed_embedding, face2.normed_embedding)
            item.update(
                {
                    "similarity": similarity,
                    "predicted": 1 if similarity >= threshold else 0,
                    "latency_ms": (time.perf_counter() - start) * 1000.0,
                }
            )
        except Exception as exc:
            item.update({"similarity": None, "predicted": None, "error": str(exc)})
            errors.append({"index": index, "error": str(exc), "row": dict(row)})
        rows.append(item)
        if progress_callback:
            progress_callback(index + 1, len(pairs), f"Processed pair {index + 1}/{len(pairs)}")

    completed = [row for row in rows if row.get("similarity") is not None]

View on GitHub (pinned to 7fadd420c2)

Solutions

1. Verify both images actually contain a visible, reasonably sized face (manually inspect the pair reported in the failing item)
2. Pre-orient images (apply EXIF rotation / deskew scans) before running the evaluation
3. If images are ID scans, crop or upscale the face region so the detector's minimum size is met
4. Treat the item as skipped/errored in the report rather than aborting the whole run

Example fix

// before
face1 = engine.detect_best_face(img1, source_path=image1_path)
face2 = engine.detect_best_face(img2, source_path=image2_path)
if face1 is None or face2 is None:
    raise ValueError("failed detection")
// after
face1 = engine.detect_best_face(img1, source_path=image1_path)
face2 = engine.detect_best_face(img2, source_path=image2_path)
if face1 is None or face2 is None:
    item.update({"similarity": None, "predicted": None, "error": "failed detection"})
    continue

face1 = engine.detect_best_face(img1)
face2 = engine.detect_best_face(img2)
if face1 is None or face2 is None:
    skip_pair("no face in pair")

def pair_is_scorable(img1, img2) -> bool:
    f1 = engine.detect_best_face(img1)
    f2 = engine.detect_best_face(img2)
    return f1 is not None and f2 is not None

try:
    run_kyc_pairs_evaluation(...)
except ValueError as e:
    if str(e) == "failed detection": mark_pair_errored()

When it happens

Trigger: 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.

Common situations: Document scans (ID cards, passports) with tiny face regions, EXIF-rotated photos, low-resolution selfies, or blank/corrupt files dropped into the evaluation dataset.

Related errors

• no face detected
• multiple faces detected ({face_count}); expected exactly one
• skipped multi-face image ({face_count} faces)
• no face or embedding
• embedding unavailable

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