{"record":{"id":"c52cc12458412d4d","repo":"deepinsight/insightface","slug":"image-must-be-numpy-ndarray-or-imagestream","errorCode":null,"errorMessage":"Image must be numpy.ndarray or ImageStream","messagePattern":"Image must be numpy\\.ndarray or ImageStream","errorType":"validation","errorClass":"InvalidInputError","httpStatus":null,"severity":"error","filePath":"cpp-package/inspireface/python/inspireface/modules/inspireface.py","lineNumber":568,"sourceCode":"        feature_length = HInt32()\n        HFGetFeatureLength(byref(feature_length))\n\n        feature = np.zeros((feature_length.value,), dtype=np.float32)\n        ret = HFFaceFeatureExtractCpy(self._sess, stream.handle, face_information._token,\n                                      feature.ctypes.data_as(ctypes.POINTER(HFloat)))\n\n        check_error(ret, \"Face feature extraction\", track_id=face_information.track_id)\n        return feature\n\n    @staticmethod\n    def _get_image_stream(image):\n        \"\"\"Convert image to ImageStream if needed\"\"\"\n        if isinstance(image, np.ndarray):\n            return ImageStream.load_from_cv_image(image)\n        elif isinstance(image, ImageStream):\n            return image\n        else:\n            raise InvalidInputError(\"Image must be numpy.ndarray or ImageStream\", \n                                   context={'input_type': type(image).__name__})\n\n    @staticmethod\n    def _get_processing_function_and_param(exec_param):\n        \"\"\"Get processing function and parameters\"\"\"\n        if isinstance(exec_param, SessionCustomParameter):\n            return HFMultipleFacePipelineProcess, exec_param._c_struct(), \"object\"\n        elif isinstance(exec_param, int):\n            return HFMultipleFacePipelineProcessOptional, exec_param, \"bitmask\"\n        else:\n            raise InvalidInputError(\"exec_param must be SessionCustomParameter or int\",\n                                   context={'param_type': type(exec_param).__name__})\n\n    def _update_mask_confidence(self, exec_param, flag, extends):\n        \"\"\"Update mask confidence in extends list\"\"\"\n        if (flag == \"object\" and exec_param.enable_mask_detect) or (\n                flag == \"bitmask\" and exec_param & HF_ENABLE_MASK_DETECT):\n            mask_results = HFFaceMaskConfidence()","sourceCodeStart":550,"sourceCodeEnd":586,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/cpp-package/inspireface/python/inspireface/modules/inspireface.py#L550-L586","documentation":"InspireFaceSession._get_image_stream accepts only np.ndarray (converted via ImageStream.load_from_cv_image) or an already-built ImageStream; anything else raises InvalidInputError with the offending input_type recorded. It is the single normalization point used by face_detection, face_pipeline, and face_feature_extract.","triggerScenarios":"Passing PIL.Image, str path, bytes, list, or None to any of the three processing methods instead of an ndarray/ImageStream.","commonSituations":"Porting PIL-based code; passing file paths expecting the library to read them (it doesn't); reusing variables that are None after a failed load.","solutions":["Load with cv2.imread(path) and pass the ndarray (check not None)","Reuse an ImageStream when calling multiple methods on the same frame","Convert PIL: cv2.cvtColor(np.array(img), cv2.COLOR_RGB2BGR)"],"exampleFix":"# before\nfaces = session.face_detection('photo.jpg')\n# after\nimport cv2\nimg = cv2.imread('photo.jpg')\nassert img is not None\nfaces = session.face_detection(img)","handlingStrategy":"type-guard","validationCode":"import cv2\nimg = cv2.imread(path)\nif img is None:\n    raise FileNotFoundError(path)","typeGuard":"def is_pipeline_image(img) -> bool:\n    import numpy as np\n    from inspireface.modules.core.image_stream import ImageStream\n    return isinstance(img, (np.ndarray, ImageStream))","tryCatchPattern":null,"preventionTips":["Centralize image loading (cv2.imread + None check) in one helper","Convert PIL/tensor inputs at the boundary of your code"],"tags":["validation","image","type-error","inspireface"],"backgroundTag":"input-type-validation-failed","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}