deepinsight/insightface · error · ValueError

image read failure

Error message

image read failure

What it means

Raised by _detect_faces_for_image when read_image returns None for a path, meaning the file could not be loaded as an image (missing, corrupt, unsupported, or unreadable). Detection never runs; the caller (_embedding_for_image or _validate_image_spec) records the failure or propagates it.

Source

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

    if policy == MULTI_FACE_REQUIRE_ONE:
        return "Multi-face policy: require exactly one face. Images with multiple detected faces fail with a clear error."
    if policy == MULTI_FACE_USE_LARGEST:
        return "Multi-face policy: use largest face. If an image has multiple faces, the largest detected face is used."
    if policy == MULTI_FACE_USE_CENTERED_LARGEST:
        return (
            "Multi-face policy: use largest centered face. If an image has multiple faces, the face with the best "
            "area-minus-center-distance score is used."
        )
    return (
        "Multi-face policy: mark as skip. Gallery images with multiple detected faces are skipped; a multi-face query "
        "stops the current run."
    )


def _detect_faces_for_image(path: Path, engine: FaceEngine):
    img = read_image(path)
    if img is None:
        raise ValueError("image read failure")
    return img, engine.detect_faces(img, source_path=str(path))


def _embedding_for_image(
    path: Path,
    engine: FaceEngine,
    cache: Dict[str, np.ndarray],
    errors: List[Dict[str, Any]],
    stage: str,
    multi_face_policy: str = MULTI_FACE_REQUIRE_ONE,
) -> Optional[np.ndarray]:
    key = str(path)
    if key in cache:
        return cache[key]
    policy = _normalize_multi_face_policy(multi_face_policy)
    try:
        image, faces = _detect_faces_for_image(path, engine)
        face = _select_face_from_faces(faces, image.shape, path, policy, stage)

View on GitHub (pinned to 7fadd420c2)

Solutions

1. Verify the path exists and is a regular file before evaluation (Path.is_file())
2. Open the file with PIL/cv2 manually to identify corrupt or unsupported images
3. Re-encode problematic images to standard RGB JPEG/PNG
4. Filter bad paths up front with a validation pass using list_images/_validate_image_spec

Example fix

# before
image, faces = _detect_faces_for_image(path, engine)
# after
if not path.is_file():
    raise FileNotFoundError(path)
image, faces = _detect_faces_for_image(path, engine)

from pathlib import Path
from PIL import Image
p = Path(path)
assert p.is_file()
with Image.open(p) as im:
    im.verify()  # raises on corrupt files

try:
    image, faces = _detect_faces_for_image(path, engine)
except ValueError as e:
    if "image read failure" in str(e):
        log_bad_image(path); skip(path)

When it happens

Trigger: Passing a nonexistent path, a corrupt/truncated file, a non-image file, or an unreadable (permissions/codec) file to an evaluation that calls _detect_faces_for_image.

Common situations: Dataset manifests with stale paths; files with wrong extension (.jpg that is actually text); CMYK/exotic JPEG variants; files synced partially; permission issues on mounted storage.

Related errors

• skipped multi-face image ({face_count} faces)
• no face or embedding
• No verification pairs could be generated from the selected i
• No gallery embeddings could be extracted.
• Target image could not be read.

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