deepinsight/insightface · error · InvalidInputError

Image must be numpy.ndarray or ImageStream

Error message

Image must be numpy.ndarray or ImageStream

What it means

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.

Solutions

1. Load with cv2.imread(path) and pass the ndarray (check not None)
2. Reuse an ImageStream when calling multiple methods on the same frame
3. Convert PIL: cv2.cvtColor(np.array(img), cv2.COLOR_RGB2BGR)

Example fix

# before
faces = session.face_detection('photo.jpg')
# after
import cv2
img = cv2.imread('photo.jpg')
assert img is not None
faces = session.face_detection(img)

import cv2
img = cv2.imread(path)
if img is None:
    raise FileNotFoundError(path)

def is_pipeline_image(img) -> bool:
    import numpy as np
    from inspireface.modules.core.image_stream import ImageStream
    return isinstance(img, (np.ndarray, ImageStream))

When it happens

Trigger: Passing PIL.Image, str path, bytes, list, or None to any of the three processing methods instead of an ndarray/ImageStream.

Common situations: 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.

Related errors

• HERR_INVALID_PARAM
• exec_param must be SessionCustomParameter or int
• HERR_INVALID_FACE_FEATURE
• HERR_INVALID_IMAGE_STREAM_PARAM
• Model ' ' not found. Available models

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

Appendix: source

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

        feature_length = HInt32()
        HFGetFeatureLength(byref(feature_length))

        feature = np.zeros((feature_length.value,), dtype=np.float32)
        ret = HFFaceFeatureExtractCpy(self._sess, stream.handle, face_information._token,
                                      feature.ctypes.data_as(ctypes.POINTER(HFloat)))

        check_error(ret, "Face feature extraction", track_id=face_information.track_id)
        return feature

    @staticmethod
    def _get_image_stream(image):
        """Convert image to ImageStream if needed"""
        if isinstance(image, np.ndarray):
            return ImageStream.load_from_cv_image(image)
        elif isinstance(image, ImageStream):
            return image
        else:
            raise InvalidInputError("Image must be numpy.ndarray or ImageStream", 
                                   context={'input_type': type(image).__name__})

    @staticmethod
    def _get_processing_function_and_param(exec_param):
        """Get processing function and parameters"""
        if isinstance(exec_param, SessionCustomParameter):
            return HFMultipleFacePipelineProcess, exec_param._c_struct(), "object"
        elif isinstance(exec_param, int):
            return HFMultipleFacePipelineProcessOptional, exec_param, "bitmask"
        else:
            raise InvalidInputError("exec_param must be SessionCustomParameter or int",
                                   context={'param_type': type(exec_param).__name__})

    def _update_mask_confidence(self, exec_param, flag, extends):
        """Update mask confidence in extends list"""
        if (flag == "object" and exec_param.enable_mask_detect) or (
                flag == "bitmask" and exec_param & HF_ENABLE_MASK_DETECT):
            mask_results = HFFaceMaskConfidence()

View on GitHub (pinned to 7fadd420c2)