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.

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)

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
• HERR_INVALID_IMAGE_STREAM_PARAM
• HERR_INVALID_FACE_FEATURE
• Session parameter must be SessionCustomParameter or int
• exec_param must be SessionCustomParameter or int

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