{"record":{"id":"a56c28a5c8d9b7a5","repo":"deepinsight/insightface","slug":"embedding-unavailable","errorCode":null,"errorMessage":"embedding unavailable","messagePattern":"embedding unavailable","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python-package/insightface/gui/core/evaluation.py","lineNumber":1010,"sourceCode":"    for index, row in enumerate(pairs):\n        if cancel_callback and cancel_callback():\n            break\n        image1_path = row.get(\"image1_path\") or row.get(\"image1\") or \"\"\n        image2_path = row.get(\"image2_path\") or row.get(\"image2\") or \"\"\n        label = int(row.get(\"label\", \"0\"))\n        item: Dict[str, Any] = {\"image1_path\": image1_path, \"image2_path\": image2_path, \"label\": label}\n        start = time.perf_counter()\n        try:\n            img1 = read_image(image1_path)\n            img2 = read_image(image2_path)\n            if img1 is None or img2 is None:\n                raise ValueError(\"image read failure\")\n            face1 = engine.detect_best_face(img1, source_path=image1_path)\n            face2 = engine.detect_best_face(img2, source_path=image2_path)\n            if face1 is None or face2 is None:\n                raise ValueError(\"failed detection\")\n            if face1.normed_embedding is None or face2.normed_embedding is None:\n                raise ValueError(\"embedding unavailable\")\n            similarity = cosine_similarity(face1.normed_embedding, face2.normed_embedding)\n            item.update(\n                {\n                    \"similarity\": similarity,\n                    \"predicted\": 1 if similarity >= threshold else 0,\n                    \"latency_ms\": (time.perf_counter() - start) * 1000.0,\n                }\n            )\n        except Exception as exc:\n            item.update({\"similarity\": None, \"predicted\": None, \"error\": str(exc)})\n            errors.append({\"index\": index, \"error\": str(exc), \"row\": dict(row)})\n        rows.append(item)\n        if progress_callback:\n            progress_callback(index + 1, len(pairs), f\"Processed pair {index + 1}/{len(pairs)}\")\n\n    completed = [row for row in rows if row.get(\"similarity\") is not None]\n    metrics = _metrics_at_threshold(completed, threshold)\n    metrics.update(","sourceCodeStart":992,"sourceCodeEnd":1028,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/python-package/insightface/gui/core/evaluation.py#L992-L1028","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Confirm a recognition model (e.g. arcface w600k) is loaded alongside the detector in the Models page","Check that the face bbox is valid (non-zero area) for the failing pair","Re-download or re-verify the model pack if embeddings are consistently None","Skip and record the pair as unscoreable instead of failing the run"],"exampleFix":"// before\nif face1.normed_embedding is None or face2.normed_embedding is None:\n    raise ValueError(\"embedding unavailable\")\n// after\nif face1.normed_embedding is None or face2.normed_embedding is None:\n    item.update({\"similarity\": None, \"predicted\": None, \"error\": \"embedding unavailable\"})\n    continue","handlingStrategy":"validation","validationCode":"if not engine.is_loaded():\n    engine.load()\nface = engine.detect_best_face(img1)\nif face is None or face.normed_embedding is None:\n    skip_pair(\"embedding unavailable\")","typeGuard":"def has_embedding(face) -> bool:\n    return face is not None and face.normed_embedding is not None","tryCatchPattern":"try:\n    run_kyc_pairs_evaluation(...)\nexcept ValueError as e:\n    if str(e) == \"embedding unavailable\": reload_models_and_retry()","preventionTips":["Always verify recognition model is loaded before evaluation","Check normed_embedding on detected faces before scoring","Skip and log unscoreable pairs"],"tags":["embedding","recognition-model","kyc","evaluation"],"backgroundTag":"model-not-loaded-missing-embedding","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}