deepinsight/insightface · error · ValueError

1:N without Auto Split requires gallery/ and probe/ folders.

Error message

1:N without Auto Split requires gallery/ and probe/ folders.

What it means

Raised by _collect_gallery_probe_structured when running 1:N identification without auto_split and the dataset root lacks either a gallery/ or probe/ subdirectory. The structured mode requires a specific directory layout: root/gallery/<identity>/* and root/probe/<identity>/* (plus optional root/unknown/).

Source

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

    gallery_items: List[Dict[str, Any]] = []
    probe_items: List[Dict[str, Any]] = []
    identities_root = _identity_root_for_auto_split(root)
    for identity_dir in _identity_dirs(identities_root):
        gallery, probes = _auto_split_identity_images(identity_dir)
        if gallery is None:
            continue
        identity = _identity_name(identity_dir)
        gallery_items.append({"identity": identity, "path": gallery})
        probe_items.extend({"identity": identity, "path": path} for path in probes)
    return gallery_items, probe_items, []


def _collect_gallery_probe_structured(root: Path) -> tuple[List[Dict[str, Any]], List[Dict[str, Any]], List[Path]]:
    gallery_root = root / "gallery"
    probe_root = root / "probe"
    unknown_root = root / "unknown"
    if not gallery_root.is_dir() or not probe_root.is_dir():
        raise ValueError("1:N without Auto Split requires gallery/ and probe/ folders.")
    gallery_items: List[Dict[str, Any]] = []
    probe_items: List[Dict[str, Any]] = []
    for identity_dir in _identity_dirs(gallery_root):
        identity = _identity_name(identity_dir)
        gallery_items.extend({"identity": identity, "path": path} for path in sorted(list_images(identity_dir, recursive=True)))
    for identity_dir in _identity_dirs(probe_root):
        identity = _identity_name(identity_dir)
        probe_items.extend({"identity": identity, "path": path} for path in sorted(list_images(identity_dir, recursive=True)))
    unknown_items = sorted(list_images(unknown_root, recursive=True)) if unknown_root.is_dir() else []
    return gallery_items, probe_items, unknown_items


def _rank_identities(query_embedding: np.ndarray, gallery: List[Dict[str, Any]]) -> List[tuple[str, float]]:
    best_by_identity: Dict[str, float] = {}
    for sample in gallery:
        score = cosine_similarity(query_embedding, sample["embedding"])
        identity = str(sample["identity"])
        if identity not in best_by_identity or score > best_by_identity[identity]:

View on GitHub (pinned to 7fadd420c2)

Solutions

1. Create gallery/ and probe/ subdirectories under dataset_root, each containing per-identity folders
2. Or set auto_split=True to have the library split flat identity folders automatically
3. Double-check exact lowercase folder names gallery and probe
4. Point dataset_root at the parent that actually contains these subfolders

Example fix

# directory layout required (auto_split=False)
# root/
#   gallery/alice/1.jpg
#   probe/alice/2.jpg
#   unknown/stranger.jpg
result = run_identity_identification_evaluation(root, auto_split=False)

from pathlib import Path
root = Path(dataset_root)
if not (root / "gallery").is_dir() or not (root / "probe").is_dir():
    # either create structure or use auto_split=True
    auto_split = True

try:
    result = run_identity_identification_evaluation(root, auto_split=False)
except ValueError as e:
    if "requires gallery/ and probe/" in str(e):
        result = run_identity_identification_evaluation(root, auto_split=True)

When it happens

Trigger: Calling run_identity_identification_evaluation with auto_split=False on a root that has identity folders directly (flat layout) instead of gallery/ and probe/ subfolders.

Common situations: Mixing up auto-split and structured layouts; wrong dataset_root level; folder named 'Gallery' (case) or 'test' instead of 'probe'; dataset downloaded in flat LFW-style layout.

Related errors

• 1:N evaluation requires at least one gallery image.
• 1:N evaluation requires at least one known probe image.
• skipped multi-face image ({face_count} faces)
• image read failure
• no face or embedding

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