deepinsight/insightface · error · ValueError

embedding unavailable

Error message

embedding unavailable

What it means

Raised by run_kyc_pairs_evaluation when a detected face lacks a normed_embedding, i.e. the recognition model did not produce an embedding for that face crop. Comparison requires embeddings from both faces, so the pair cannot be scored.

Source

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

    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]
    metrics = _metrics_at_threshold(completed, threshold)
    metrics.update(

View on GitHub (pinned to 7fadd420c2)

Solutions

1. Confirm a recognition model (e.g. arcface w600k) is loaded alongside the detector in the Models page
2. Check that the face bbox is valid (non-zero area) for the failing pair
3. Re-download or re-verify the model pack if embeddings are consistently None
4. Skip and record the pair as unscoreable instead of failing the run

Example fix

// before
if face1.normed_embedding is None or face2.normed_embedding is None:
    raise ValueError("embedding unavailable")
// after
if face1.normed_embedding is None or face2.normed_embedding is None:
    item.update({"similarity": None, "predicted": None, "error": "embedding unavailable"})
    continue

if not engine.is_loaded():
    engine.load()
face = engine.detect_best_face(img1)
if face is None or face.normed_embedding is None:
    skip_pair("embedding unavailable")

def has_embedding(face) -> bool:
    return face is not None and face.normed_embedding is not None

try:
    run_kyc_pairs_evaluation(...)
except ValueError as e:
    if str(e) == "embedding unavailable": reload_models_and_retry()

When it happens

Trigger: detect_best_face succeeds (a face is found) but face.normed_embedding is None — typically when the recognition model is not loaded or the face crop fails recognition preprocessing.

Common situations: Running KYC evaluation with only a detection model loaded (no recognition/embedding model), mismatched model pack versions, or a degenerate face crop (0-size bbox) that breaks embedding generation.

Related errors

• no face or embedding
• No gallery embeddings could be extracted.
• failed detection
• Identity folder root not found: {root}
• no face detected

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