What causes "{operation}: Feature data must be a numpy array" in deepinsight/insightface?

Wrap: np.asarray(feature, dtype=np.float32)

deepinsight/insightface · error · InvalidInputError

HERR_INVALID_FACE_FEATURE

HERR_INVALID_FACE_FEATURE

Error message

{operation}: Feature data must be a numpy array

What it means

validate_feature_data() requires face feature embeddings to be numpy arrays before comparing/searching them; passing a list, tuple, tensor, or None raises InvalidInputError with HERR_INVALID_FACE_FEATURE. Feature vectors drive comparison and FeatureHub search, so they must be concrete contiguous arrays.

Source

Thrown at cpp-package/inspireface/python/inspireface/modules/exception.py:202

            errcode.HERR_INVALID_IMAGE_STREAM_PARAM,
            actual_shape=image.shape
        )
    
    h, w, c = image.shape
    if c not in [3, 4]:
        raise InvalidInputError(
            f"{operation}: Image must have 3 or 4 channels",
            errcode.HERR_INVALID_IMAGE_STREAM_PARAM,
            actual_channels=c
        )


def validate_feature_data(data, operation: str = "Feature validation"):
    """Validate feature data format"""
    import numpy as np
    
    if not isinstance(data, np.ndarray):
        raise InvalidInputError(
            f"{operation}: Feature data must be a numpy array",
            errcode.HERR_INVALID_FACE_FEATURE,
            input_type=type(data).__name__
        )
    
    if data.dtype != np.float32:
        raise InvalidInputError(
            f"{operation}: Feature data must be in float32 format",
            errcode.HERR_INVALID_FACE_FEATURE,
            actual_dtype=str(data.dtype)
        )


def validate_session_initialized(session, operation: str = "Session operation"):
    """Validate if session is initialized"""
    if session is None or session._sess is None:
        raise ResourceError(
            f"{operation}: Session not initialized",

View on GitHub (pinned to 7fadd420c2)

Solutions

Wrap: np.asarray(feature, dtype=np.float32)
After JSON round-trips: np.array(json.loads(s), dtype=np.float32)
For tensors: feature.cpu().numpy()

Example fix

# before
feature = [0.1, 0.2, 0.3]  # list from JSON
sim = session.feature_comparison(feature, other)
# after
import numpy as np
feature = np.asarray(feature, dtype=np.float32)
sim = session.feature_comparison(feature, other)

Defensive patterns

Strategy: type-guard

Validate before calling

import numpy as np
feature = np.asarray(raw_feature, dtype=np.float32)

Type guard

def is_valid_feature(f) -> bool:
    import numpy as np
    return isinstance(f, np.ndarray)

Try / catch

from inspireface.modules.exception import InvalidInputError
try:
    session.feature_comparison(a, b)
except InvalidInputError:
    a, b = np.asarray(a, np.float32), np.asarray(b, np.float32)
    session.feature_comparison(a, b)

Prevention

Convert features to np.float32 arrays immediately after extraction and before persistence
Wrap JSON-deserialized features in np.asarray(..., dtype=np.float32)

When it happens

Trigger: Calling feature_comparison, feature_hub_face_search, feature_hub_face_search_top_k, or constructing an object that takes a feature, with a plain Python list/tuple/torch tensor instead of an ndarray.

Common situations: Serializing features to JSON (which turns them into lists) and feeding them back; copying notebook examples that print a feature as a list; interop with PyTorch/TF tensors.

Related errors

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