{"record":{"id":"e3cb04169af73b38","repo":"deepinsight/insightface","slug":"herr-invalid-face-feature","errorCode":"HERR_INVALID_FACE_FEATURE","errorMessage":"{operation}: Feature data must be a numpy array","messagePattern":"(.+?): Feature data must be a numpy array","errorType":"validation","errorClass":"InvalidInputError","httpStatus":null,"severity":"error","filePath":"cpp-package/inspireface/python/inspireface/modules/exception.py","lineNumber":202,"sourceCode":"            errcode.HERR_INVALID_IMAGE_STREAM_PARAM,\n            actual_shape=image.shape\n        )\n    \n    h, w, c = image.shape\n    if c not in [3, 4]:\n        raise InvalidInputError(\n            f\"{operation}: Image must have 3 or 4 channels\",\n            errcode.HERR_INVALID_IMAGE_STREAM_PARAM,\n            actual_channels=c\n        )\n\n\ndef validate_feature_data(data, operation: str = \"Feature validation\"):\n    \"\"\"Validate feature data format\"\"\"\n    import numpy as np\n    \n    if not isinstance(data, np.ndarray):\n        raise InvalidInputError(\n            f\"{operation}: Feature data must be a numpy array\",\n            errcode.HERR_INVALID_FACE_FEATURE,\n            input_type=type(data).__name__\n        )\n    \n    if data.dtype != np.float32:\n        raise InvalidInputError(\n            f\"{operation}: Feature data must be in float32 format\",\n            errcode.HERR_INVALID_FACE_FEATURE,\n            actual_dtype=str(data.dtype)\n        )\n\n\ndef validate_session_initialized(session, operation: str = \"Session operation\"):\n    \"\"\"Validate if session is initialized\"\"\"\n    if session is None or session._sess is None:\n        raise ResourceError(\n            f\"{operation}: Session not initialized\",","sourceCodeStart":184,"sourceCodeEnd":220,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/cpp-package/inspireface/python/inspireface/modules/exception.py#L184-L220","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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()"],"exampleFix":"# before\nfeature = [0.1, 0.2, 0.3]  # list from JSON\nsim = session.feature_comparison(feature, other)\n# after\nimport numpy as np\nfeature = np.asarray(feature, dtype=np.float32)\nsim = session.feature_comparison(feature, other)","handlingStrategy":"type-guard","validationCode":"import numpy as np\nfeature = np.asarray(raw_feature, dtype=np.float32)","typeGuard":"def is_valid_feature(f) -> bool:\n    import numpy as np\n    return isinstance(f, np.ndarray)","tryCatchPattern":"from inspireface.modules.exception import InvalidInputError\ntry:\n    session.feature_comparison(a, b)\nexcept InvalidInputError:\n    a, b = np.asarray(a, np.float32), np.asarray(b, np.float32)\n    session.feature_comparison(a, b)","preventionTips":["Convert features to np.float32 arrays immediately after extraction and before persistence","Wrap JSON-deserialized features in np.asarray(..., dtype=np.float32)"],"tags":["validation","feature-embedding","numpy","inspireface"],"backgroundTag":"invalid-feature-format","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}